Shrouding and Binding

Binding and Shrouding

The Shroud Command

Synopsis:

     shroud [-full_debug] [-list] [-quiet] [-out shrouded_file] filename.ex[w/u]

The shroud command converts a Euphoria program, typically consisting of a main file plus many include files, into a single, compact file. A single file is not only convenient, it allows you to give people your program to use, without giving them your source code.

A shrouded file does not contain any Euphoria source code statements. Rather, it contains a low-level intermediate language (IL) that is executed by the back-end of the interpreter. A shrouded file does not require any parsing. It starts running immediately, and with large programs you will see a quicker start-up time. Shrouded files must be run using the interpreter back-end: backend.exe (DOS), backendw.exe (Windows) or backendu (Linux/FreeBSD). This backend is freely available, and you can give it to any of your users who need it. It's stored in euphoria\bin in the Euphoria interpreter package. On DOS you can run your .il file with:

      backend myprog.il

On Windows use:

      backendw myprog.il

On Linux or FreeBSD use:

      backendu myprog.il

Although it does not contain any source statements, a .il file will generate a useful ex.err dump in case of a run-time error.

The shrouder will remove any routines and variables that your program doesn't use. This will give you a smaller .il file. There are often a great number of unused routines and unused variables. For example your program might include several 3rd party include files, plus some standard files from euphoria\include, but only use a few items from each file. The unused items will be deleted.

options can be:

-full_debug - Make a somewhat larger .il file that contains enough debug information to provide a full ex.err dump when a crash occurs.
Normally, variable names and line-number information is stripped out of the .il file, so the ex.err will simply have "no-name" where each variable name should be, and line numbers will only be accurate to the start of a routine or the start of a file. Only the private variable values are shown, not the global or local values. In addition to saving space, some people might prefer that the shrouded file, and any ex.err file, not expose as much information.

-list - Produce a listing in deleted.txt of the routines and constants that were deleted.

-quiet - Suppress normal messages and statistics. Only report errors.

-out shrouded_file - Write the output to shrouded_file.

The Euphoria interpreter will not perform tracing on a shrouded file. You must trace your original source.

On Linux/FreeBSD, the shrouder will make your shrouded file executable, and will add a #! line at the top, that will run backendu. You can override this #! line by specifying your own #! line at the top of your main Euphoria file.

Always keep a copy of your original source. There's no way to recover it from a shrouded file.

The Bind Command

Synopsis:

     bind  [-full_debug] [-list] [-quiet] [-out executable_file] [filename.ex]
     bindu [-full_debug] [-list] [-quiet] [-out executable_file] [filename.exu]
     bindw [-full_debug] [-list] [-quiet] [-out executable_file] [-con] [-icon filename.ico] [filename.exw]

bind (bindw or bindu) does the same thing as shroud, and includes the same options. It then combines your shrouded .il file with the interpreter backend (backend.exe, backendw.exe or backendu) to make a single, stand-alone executable file that you can conveniently use and distribute. Your users need not have Euphoria installed. Each time your executable file is run, a quick integrity check is performed to detect any tampering or corruption. Your program will start up very quickly since no parsing is needed.

The Euphoria interpreter will not perform tracing on a bound file since the source statements are not there.

options can be:

-full_debug - Same as shroud above. If Euphoria detects an error, your executable will generate either a partial, or a full, ex.err dump, according to this option.

-list - Same as shroud above.

-quiet - Same as shroud above.

-out executable_file - This option lets you choose the name of the executable file created by the binder. Without this option, bind will choose a name based on the name of the main Euphoria source file.

-con - (bindw only) This option will create a Windows console program instead of a Windows GUI program. Console programs can access standard input and output, and they work within the current console window, rather than popping up a new one.

-icon filename[.ico] - (bindw only) When you bind a program, you can patch in your own customized icon, overwriting the one in exw.exe. exw.exe contains a 32x32 icon using 256 colors. It resembles an E) shape. Windows will display this shape beside exw.exe, and beside your bound program, in file listings. You can also load this icon as a resource, using the name "exw" (see euphoria\demo\win32\window.exw for an example). When you bind your program, you can substitute your own 32x32 256-color icon file of size 2238 bytes or less. Other dimensions may also work as long as the file is 2238 bytes or less. The file must contain a single icon image (Windows will create a smaller or larger image as necessary). The default E) icon file, euphoria.ico, is included in the euphoria\bin directory.

A one-line Euphoria program will result in an executable file as large as the back-end you are binding with, but the size increases very slowly as you add to your program. When bound, the entire Euphoria editor, ed.ex, adds only 27K to the size of the back-end. backendw.exe and backendu (Linux) are compressed using UPX (see http://upx.sourceforge.net). backend.exe is compressed using a tool that comes with the CauseWay DOS extender. backend.exe is the largest of the three since it includes a lot of pixel graphics routines, not part of backendw.exe or backendu. Note: In some very rare cases, a compressed executable may trigger a warning message from a virus scanner. This is simply because the executable file looks abnormal to the virus scanner.

The first two arguments returned by the command_line() library routine will be slightly different when your program is bound. See library.doc for the details.

A bound executable file can handle standard input and output redirection. e.g.

        myprog.exe < file.in > file.out

If you were to write a small DOS .bat file myprog.bat that contained the line "ex myprog.ex" you would not be able to redirect input and output in the following manner:

        myprog.bat < file.in > file.out     (doesn't work in DOS!)

You could however use redirection on individual lines within the .bat file.

-full_debug	-	Make a somewhat larger .il file that contains enough debug information to provide a full ex.err dump when a crash occurs. Normally, variable names and line-number information is stripped out of the .il file, so the ex.err will simply have "no-name" where each variable name should be, and line numbers will only be accurate to the start of a routine or the start of a file. Only the private variable values are shown, not the global or local values. In addition to saving space, some people might prefer that the shrouded file, and any ex.err file, not expose as much information.
-list	-	Produce a listing in deleted.txt of the routines and constants that were deleted.
-quiet	-	Suppress normal messages and statistics. Only report errors.
-out shrouded_file	-	Write the output to shrouded_file.

-full_debug	-	Same as shroud above. If Euphoria detects an error, your executable will generate either a partial, or a full, ex.err dump, according to this option.
-list	-	Same as shroud above.
-quiet	-	Same as shroud above.
-out executable_file	-	This option lets you choose the name of the executable file created by the binder. Without this option, bind will choose a name based on the name of the main Euphoria source file.
-con	-	(bindw only) This option will create a Windows console program instead of a Windows GUI program. Console programs can access standard input and output, and they work within the current console window, rather than popping up a new one.
-icon filename[.ico]	-	(bindw only) When you bind a program, you can patch in your own customized icon, overwriting the one in exw.exe. exw.exe contains a 32x32 icon using 256 colors. It resembles an E) shape. Windows will display this shape beside exw.exe, and beside your bound program, in file listings. You can also load this icon as a resource, using the name "exw" (see euphoria\demo\win32\window.exw for an example). When you bind your program, you can substitute your own 32x32 256-color icon file of size 2238 bytes or less. Other dimensions may also work as long as the file is 2238 bytes or less. The file must contain a single icon image (Windows will create a smaller or larger image as necessary). The default E) icon file, euphoria.ico, is included in the euphoria\bin directory.