OS/2 Shareware BBS: 10 Tools/10-Tools.zip/shroud.zip/READ.ME

Text File | 1989-11-25 | 15KB | 346 lines

                  C-Language Source Code Shrouder, Version 2

  Thank you for downloading my C-language source code shrouder!

  This program may be used to shroud your C language source code, so that you
can give it to others without giving away your hard work.

  I wrote this program so that users of Watcom's excellent C compiler may
safely send their source code to Watcom's customer support staff.  Sometimes,
source code is necessary to isolate and correct bugs in Watcom's products.

  By the way, isn't it great to see bugs get fixed quickly?!  How often have
you had to deal with "that other" C compiler vendor because their loop
optimization has bugs?  I would like to commend Karen Ali, Jan Young, Brian
Stecher, Fred Crigger, and others at Watcom for their excellent support of
their important new product!

                        What is "Shrouded" Source Code?

  Shrouded source code is just your original source code, with comments
removed, and rearranged so that the meaning is the same, but no reasonable
human being would ever want to decipher it.

  Sometimes, you may encounter a bug in a compiler that can only be easily
reproduced with your original source code.  In this case, the compiler
vendor's customer support staff will need your source code to reproduce and
correct the problem.

  But you, or your employer, may object to sending the source code "off-site",
even if only one module is needed to reproduce the problem.  That is when
shrouding can help.

  Just run your source code through this shrouder, and send the shrouded
source code to the compiler vendor.  Chances are that the problem will be
demonstrated by the shrouded source code just as well as by the original
source code.  (So that you don't waste the vendor's time, you should verify
that it does, if possible, before sending it.)

                       Distributing Shrouded Source Code

  Shrouding has other uses as well.  Some UNIX software vendors distribute
their products in shrouded-source-code form.  This is because UNIX is
available on a number of disparate processors and environments.  A UNIX
software vendor can send his shrouded source code to his customers.  The
customer can then compile it in his own environment.  The vendor has not
disclosed his source code, and yet is able to support numerous environments.

  This shrouder can work in this way, within certain limits.  If you write
your source code well, then it can be shrouded with this program and
distributed with confidence that it will work when compiled in various
environments.  See SHROUD.MAN for more information.

  More sophisticated shrouders might work with less carefully-written source
code, but I'll wager none are less expensive.

                          How Does the Shrouder Work?

  The shrouder is actually just a C-language preprocessor, like the one
described in the Kernighan & Ritchie book, and in the ANSI draft standard.
However, it does two thing differently from the standard preprocessor.

  First, it replaces all of your identifiers with gobbledygook that nobody
will recognize.

  Second, it forms all of your source code (and include files) into long
lines, with no extra spaces.  This makes the code even harder to read.

  You won't see any "#define" or "#include" directives in the shrouded source
code, because all of the include files and macro invocations have been
replaced with the text they represent.  "#if" directives are already processed
as well.

  You'd be surprised at how awful the result looks to a C programmer!  Who
would have thought that grunging up your source code would have been such a
useful thing to do?

                            How To Use the Shrouder

  The shrouder is invoked with the following command:

        shroud <flags> <files>

  We'll talk about the <flags> below.

  <files> will generally be just one file, the C source code file that needs
to be shrouded.  For example, to shroud the C source code file EXAMPLE.C, use
the following command:

        shroud example.c

  The shrouded source code will appear on the screen.  Of course, this doesn't
help if you need to send it to somebody else.  You may use "I/O redirection"
to send the shrouded source code to a file (see your DOS manual).  For
example, the following command will deposit the shrouded source code in the
file EXAMPLE.SHR:

        shroud example.c >example.shr

  In most cases, this is all that's required.

                             Command Line Options

  There are a few options.  These are specified in the <flags> part of the
command.

                                Defining Macros

  First, you can define an "empty" macro with the "-d" switch, as follows:

        shroud -dMACRO_NAME example.c >example.shr

  This macro will be defined as if the first line in the source file was:

        #define MACRO_NAME

  Note that macro defined in this way have no replacement text.  They are
useful only in "#ifdef" or "#if defined(...)" directives.  We'll see how to
define more complicated macros below.

                          Shrouding Library Functions

  By default, this shrouder does NOT shroud library functions, variables, and
types.  This is so that it is possible to link the result with the library.
It wouldn't do to replace "printf" with gobbledygook in your code.

  However, you may want to shroud library functions as well.  This would make
your source code even more opaque.  You should do this only if simply
compiling your one module demonstrates a problem, and thus need not be linked
with the libraries.

  The "-l" switch will cause library functions to be shrouded as well, as
follows:

        shroud -l example.c >example.shr

  (The shrouder, by default, does not shroud any identifier that is first
encountered in a file that is read as a result of an #include directive with
angle brackets, such as "#include <stdio.h>".  If you use "#include "stdio.h""
instead, the identifiers in STDIO.H will always be shrouded.  The "-l" switch
causes all identifiers to be shrouded, regardless of where they are first
encountered.)

                             Retaining Whitespace

  By default, the shrouder discards all of the whitespace (spaces, tabs,
newlines, and formfeeds) in your source code.  It forms the shrouded source
code into long lines to make it harder to read.

  However, you may want the shrouded source code to resemble your original
source code, so you can retain the original whitespace if you want.

  The "-w" switch will cause your original whitespace to be retained, as
follows:

        shroud -w example.c >example.shr

                          Watcom's Extended Keywords

  By default, the shrouder recognizes Watcom's extended keywords, such as
"near" and "huge".  These extended keywords are explained in the Watcom User's
Guide, and are similar to other compilers'.

  If you are using a compiler that does not use these unfortunate extensions,
you may want to disable their recognition.

  The "-x" switch will disable the recognition of the extended keywords.  They
will be treated as any other identifier.  This is used as follows:

        shroud -x example.c >example.shr

                        Combining Command Line Switches

  You can combine switches, within reason.  For example:

        shroud -x -l -w -dMACRO_NAME example.shr >example.shr

is equivalent to

        shroud -xlwdMACRO_NAME example.shr >example.shr

  However, this command line:

        shroud -dMACRO_NAMExlw example.shr >example.shr

is not equivalent.  It defines the macro named "MACRO_NAMExlw".  Use this
instead:

        shroud -dMACRO_NAME -xlw example.shr >example.shr

                                 Include Files

  Like the Watcom C compiler, #include files will be searched for first in the
current directory, and then in each directory named in the INCLUDE environment
variable (see your DOS manual and the Watcom User's Guide).  This environment
variable may be defined with a DOS command like this one:

        set INCLUDE=c:\wcc\h;c:\myincludes

                       Using the Shrouder To Report Bugs

  More often than not, bugs in the compiler or code generator of your C
compiler will be demonstrated just as well by shrouded source code as by your
original source code.

  On the other hand, you probably should not use the shrouder when reporting
bugs in the libraries or debugger.  In these cases, it is generally quite easy
to create a small "dummy" program that simply demonstrates the problem.  Send
the dummy program to the compiler vendor, instead of your source code that
first caused the problem.

  When reporting bugs to Watcom, you can generally use the shrouder without
any command line switches.

  I have supplied the files WATCOMS, WATCOMM, WATCOMC, WATCOML, and WATCOMH to
define Watcom's predefined macros for each memory model.  For example, if your
source code refers to Watcom's predefined macros, and is compiled for the
"large model" (see the Watcom User's Guide), use the following command line:

        shroud watcoml example.c >example.shr

  In this case, the shrouder will first read the file WATCOML, which defines
the predefined macros.  (WATCOML will not produce any shrouded output, because
it simply defines macros.)  The shrouder will then read and shroud EXAMPLE.C.

  You should compile the shrouded source with a command like the following:

        wcc example.shr

  If possible, verify that the shrouded source code demonstrates the same
problem as the original source code.  This may be as simple as observing a
compiler error message that should not appear.

  In the case of code generation problems, you may need to disassemble the
object code to verify that the problem is demonstrated.  For example:

        wdisasm -s -l example

  This command will produce the file EXAMPLE.LST, containing the shrouded
source code and the corresponding disassembled object code.  Examine
EXAMPLE.LST with you text editor, and send a note along with the EXAMPLE.SHR
and EXAMPLE.LST specifying on what line number in EXAMPLE.LST the problem may
be found.  This will make it easier for Watcom's customer support staff to
isolate the problem.

                          More Watcom Considerations

  There are a few more considerations when using the shrouder on source code
written for the Watcom C compiler.

                        The -fi (Force Include) Switch

  The Watcom compiler has a "-fi" command line switch to force inclusion of a
header file (see the Watcom User's Guide).  The shrouder has no such switch,
but it may be important to include the file.  In this case, instead of
"-fiforce.h", use a command like the following:

        shroud watcoml force.h example.c >example.shr

                         The -d (Define Macro) Switch

  The Watcom compiler has a "-d" command line switch to define macros, like
the shrouder.  However, the Watcom compiler permits "-dMACRO_NAME=value" to
give the macro a value, while the shrouder only permits "-dMACRO_NAME" to
define a macro with an empty replacement text.

  If you use the Watcom "-d" switch to define macros with values, you must
instead create a file with equivalent #define directives.  For example, create
the file MYMACROS, containing:

        #define MACRO_NAME value

  Then force the shrouder to include MYMACROS, as described above.  For
example:

        shroud watcoml mymacros example.c >example.shr

                           Watcom #pragma Directives

  The Watcom compiler provides several #pragma directives.  Even if your
source code doesn't use any of these directives, Watcom's library #include
files do use them.  It is important that the shrouded source code include the
#pragma directives, and that they don't get screwed up by shrouding.  (Since
Watcom's #pragma directives can affect code generation, the shrouded source
code might not demonstrate the same problem as the original if these
directives were discarded.)

  For this reason, the shrouder recognizes Watcom's #pragma directives, and
correctly copies them to the shrouded output.  The keywords specific to
#pragmas, like "aux" and "aborts", will not be shrouded.  Other identifiers in
#pragma directives are shrouded normally, since they probably refer to
appearances of the same identifiers elsewhere in the source code.

  Like the Watcom compiler, the shrouder replaces macros in #pragma
directives.

  Other C compiler vendors may provide other #pragmas.  These may or may not
be handled correctly by this shrouder.

                            History of the Shrouder

  This shrouder is really just a repackaging of my ANSI-conforming C language
preprocessor, which was described in an article in Computer Language, July
1988, titled "Using Tomorrow's C Standard Today".

  I have found that having source code for a C language preprocessor is a very
handy thing.  I have used it in several projects that would have been quite
difficult otherwise.

  I you would find the source code useful, just send me $15, and I will send
you source for the shrouder, preprocessor, and a YACC-generated ANSI C parser.
The parser shows how to handle the ambiguities in the ANSI C language, as well
as how to use my preprocessor to drive a YACC-generated parser for any
language.

                          Differences from Version 1

  A bug was corrected in the handling of the #elif preprocessor directive.  In
some cases, the argument to #elif was not evaluated.

  A bug was corrected in the handling of invalid tokens, such as character
constants or string literals that were missing their ending quotes.  Such
invalid tokens would consume the next newline.  If this occurred in a
preprocessor directive, the directive would consume the next line without
processing it.

                                Commercial Use

  This program may be used for private, non-commercial use only.  For
commercial use, such as to use it to distribute a commercial product, or to
incorporate it into a commercial product, contact me to make arrangements.

                                  Private Use

  Please do use this program for private use, including shrouding the source
code of your commercial products only to demonstrate problems to compiler
vendors.  Please distribute this program freely to others, provided that no
charge is made, and that this file and SHROUD.MAN are retained.

                                  Good Luck!

  Steven Bruce Williams
  Brewster Station
  P.O. Box 8458
  Bridgeport, CT 06605-0997