Shrouding and Binding
(Complete Edition only)


What is Shrouding and Binding?

In the Euphoria Complete Edition for DOS32+WIN32, shroud.bat, bind.bat, bindw.bat and bind.ex are in euphoria\bin. In the Complete Edition for Linux, you will find shroud, bindu and bind.ex in euphoria/bin. The documentation for these programs is given below.

The shroud command will prompt you for the name of your main Euphoria file, and the name of the new shrouded file that you want to create. Shrouding does the following to your program:

1. - Your main file is combined with all of the .e files that it directly or indirectly includes. This makes a single Euphoria file with no include statements.
2. - All comments and blank lines are removed.
3. - All keywords are replaced by single-byte codes.
4. - All variable names and (optionally) subroutine names are converted to short meaningless names chosen by the shroud program.
5. - (optional) All strings are converted to sequences of ASCII codes so they can't be easily read.
6. - (optional) The resulting shrouded file from steps 1 to 5 can be further "scrambled" so it becomes completely unreadable and highly tamper-resistant. For an example of a shrouded and scrambled file, have a look at bin\bind.ex

bind (bindw or bindu) does the same thing as shroud. It then combines your shrouded, and possibly scrambled, file with the Public Domain Edition ex.exe, exw.exe or exu to make a single, stand-alone executable file that you can use and distribute. Each time your executable file is run, a quick integrity check is performed to detect any tampering or corruption.

Step 5 above goes beyond the typical .exe file produced by other languages, where you can easily read character strings in the .exe. Shrouding not only conceals your source code, it also combines it into a single, very compact file.

To further enhance security, scrambling is also provided. Only RDS has the knowledge required to descramble a program and we promise never to do so. If someone managed to descramble your program, they would only recover the shrouded version of the source (after steps 1 to 5), not the original source code. The comments, and the meaningful variable and routine names can never be recovered. Always keep a copy of your original source files.


How to Shroud and Bind

Your program should at least be free of syntax errors before you bind or shroud it. If you are actively developing a program you'll find it is more convenient to run it in the normal way with ex (or exw or exu), rather than binding it and running it as a .exe file. Error messages generated against shrouded code will be difficult to relate back to your original source, since the line numbering and symbol names will be very different.

You can distribute a shrouded/scrambled .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, so your users can access routines and variables with meaningful long names, while the rest of your file remains shrouded. Try to make the global names in your .e file at least 2 or 3 characters long to avoid conflicting with any short names already assigned by the shrouder. You'll be warned if there are any naming conflicts, and the shrouder will assign a new name. In this case you might want to choose a different (longer) name for the offending global symbol.

In most cases you should simply type:

        shroud
or:
        bind
or:
        bindw
or:
        bindu
and you will be prompted for the source file name and other options.

If you type:

        shroud filename
or:
        bind filename
or:
        bindw filename
or:
        bindu filename
It will be assumed that you want:
        hide_strings: NO
        clear_routines: NO
        scramble: NO
        full_keywords: NO

shroud and bind can also be run non-interactively using command-line arguments. For example:

        bind -scramble -clear_routines myprog
or
        bindw -hide_strings myprog
This might be useful if you wish to create a .bat or shell file to automatically bind or shroud your program. The full set of command-line options is described below.

Only the Public Domain Edition interpreter files 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, 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 extremely slowly as you add to your program. When bound, the entire Euphoria editor adds only 20K to the size of the interpreter.

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.


Summary of Options for Bind and Shroud

Syntax: bind options filename.ex

bindw options filename.exw

bindu options filename.exu

shroud options filename.ex

shroud options filename.exw

shroud options filename.exu

where options can be:

-hide_strings - Convert strings to sequences of ASCII codes. This provides better shrouding, but increases the size of the shrouded file.
-clear_routines - All procedures, types and functions will retain their full name. This is needed if your program uses routine_id().

You will get warnings when routines from different included files happen to have the same name. The shrouder will pick a new name, which should be fine, unless the original name is used in a call to routine_id().

-scramble - Make the shrouded code extremely difficult to read or tamper with. Your program might load a few percent slower when you use this option.
-full_keywords - The shrouded code will contain full keywords rather than byte codes. This option is rarely used and you won't be prompted for it interactively. Only shroud supports this option.

When a shrouded or bound program has an error, the error report will refer to the shrouded code, not the original source code. Before shipping a shrouded or bound file to your users, it might be useful to run
shroud -full_keywords to get a semi-readable shrouded file that matches line for line, and symbol for symbol, with what you are shipping. Also select -hide_strings, if that's what you did in the one you are shipping. It will help you to interpret error messages that users report. It is not possible to bind the full, clear source of your program.

You can shroud or bind a program that includes a shrouded file (presumably from someone else). To include a scrambled file, you must choose the -scramble option. i.e. the level of security of the scrambled file cannot be downgraded.