🗐 Binding and Shrouding
The Shroud Command
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:
On Windows use:
On Linux or FreeBSD use:
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
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
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
-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
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
myprog.bat < file.in > file.out (doesn't work in DOS!)
You could however use redirection on individual lines within the .bat file.