🗐 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.