Shrouding and Binding
(Complete Edition only)


The Shroud Command

Synopsis:

     shroud [-clear] [-list] [-quiet] [-out shrouded_file] [filename]

The shroud command converts a Euphoria program, typically consisting of a main file plus many include files, into a single, shrouded (i.e. encrypted) file, that's easy to distribute to others. By default, the shroud command will perform the following steps:

1. - Your main .ex, .exw or .exu file is combined with all of the .e files that it directly or indirectly includes. This results in a single Euphoria file with no include statements.
2. - After making one pass through your entire program, any unused constants and routines are marked for deletion. This may expose additional constants and routines as being unused. This marking process is repeated until no more constants or routines can be deleted. A second pass is then made, where marked routines and constants are skipped, i.e. not copied to the shrouded file. It's quite common for a program to include many files, but only use a subset of the routines or constants defined in those files.
3. - All comments, blank lines, and superfluous blanks and tabs (whitespace) are removed.
4. - All keywords and standard built-in routine names are replaced by single-byte codes to save space.
5. - All user-defined names are converted to short (typically one or two letter) meaningless names chosen by the shroud program.
6. - The very compact file resulting from steps 1 to 5 is further encrypted so it becomes completely unreadable and highly tamper-resistant.

options can be:

-clear - Keep the source code in human-readable form. Unused routines and constants will be deleted, and comments and some whitespace will be removed, but the code will be otherwise unchanged. The original variable and routine names will be preserved, except where a naming conflict arises between merged files. Use this option when you want to ship a single source file, and you don't mind if people can see your code. If an error occurs while a user is running your program, the ex.err file will be readable. If you shroud your program, the ex.err file will contain short, meaningless names, and will be very difficult to understand.
-list - Produce a listing in deleted.txt of the routines and constants that were deleted, as well as any symbols that had to be renamed.
-quiet - Suppress normal messages and statistics. Only report errors.
-out shrouded_file - Write the output to shrouded_file. If you don't specify the -out option, you'll be prompted for the name of the output file.

If you simply type:

     shroud
 
without any options or filename, you'll be prompted for all the information.

shroud only performs very superficial checks on the syntax of your program. You should test your program thoroughly before shrouding or binding it.

You can distribute a shrouded .e include file that people can include in their programs without seeing your source code. Symbols declared as global in your main .e file will not be renamed or deleted, so your users can access routines and variables using meaningful long names.

You can shroud or bind a program that includes a shrouded file (presumably from someone else), however you won't be allowed to use the -CLEAR option, since this would reduce the security of the included shrouded file.

For security, the Euphoria interpreter will not perform tracing on a shrouded file, unless it is shrouded with the -clear option. In most cases it's much better to trace your original source.

Only RDS has the knowledge required to undo the encryption on a program and we have no tool to do it. Even if someone managed to undo the encryption, they would only recover the version of the source after steps 1 to 5 were applied. The comments, and the meaningful variable and routine names can never be recovered. Always keep a copy of your original source files!


The Bind Command

Synopsis:

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

bind (bindw or bindu) does the same thing as shroud, and has the same options. It then combines your shrouded (or clear text) file with the Public Domain Edition ex.exe, exw.exe or exu 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.

For security, the Euphoria interpreter will not perform tracing on a bound file, unless it is bound with the -clear option. In most cases it's much better to trace your original source.

options can be:

-clear - Same as shroud above. The .exe will contain readable code. If an error occurs, the ex.err file will be readable.
-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.
-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 Complete Edition. You can bind it, or distribute it separately, with or without your changes.

If you simply type:

     bind (or bindw or bindu) 
 
without any options or filename, you'll be prompted for all the information.

Only the Public Domain Edition interpreters can be bound. Users of the Euphoria Complete Edition for DOS32 + WIN32 will have ex.exe (Complete) and pdex.exe (Public Domain), as well as exw.exe (Complete) and pdexw.exe (Public Domain) in euphoria\bin. The bind (bindw) program will use the pdex.exe (pdexw.exe) files for binding. On Linux or FreeBSD, you'll have exu (Complete) and pdexu (Public Domain), with pdexu used for binding.

A one-line Euphoria program will result in an executable file as large as the interpreter 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 18K to the size of the interpreter. All three interpreters are compressed to reduce their size. exw.exe and exu are compressed using UPX (see http://upx.sourceforge.net). ex.exe is compressed using a tool that comes with the CauseWay DOS extender. ex.exe is the largest of the three since it includes a lot of pixel graphics routines, not part of exw.exe or exu. Note: In some 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. If demo\sanity.ex runs correctly, you can safely ignore these warnings. Otherwise contact RDS.

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.