gen-ident-exceptions.pl - a script to gather a names of symbols exported by external modules that a set of perl files uses.
gen-ident-exceptions.pl [ --include-symbols-from-exporter ] [ -p perl-path ] [ -d dir-prefix-to-exclude ].. [ -u user-exceptions-file ] .. [ -U user-exception-comma-sep-list ] .. [ -m module-exceptions-file ] .. [ -M module-exception-comma-sep-list ] .. [ -n modulenames-to-skip-file ] .. [ -N modulenames-to-skip-comma-sep-list ] .. [ -x not-exceptions-file ] .. [ -X not-exception-comma-sep-list ] .. [ -l name-of-file-with-list-of-files ] .. destfile srcfiles..
It is obvious that when obfuscating some perl file, the names of symbols the from the modules it imports should not be mangled (or obfuscated versions of all dependant modules needs to be shipped, which is not always convenient). The only way of excluding the symbol names from being mangled is to list them in file with list of exceptions. This utility is dedicated to creation of such file with list of exceptions.
The options after which there is a ellipsis (..) in the synopsis section accept a set of strings and thus may be specified several times. The values passed to such options will be merged. The values for all those options are strings that do not contain spaces and commas in them. If the value of such option contains only one space or comma, it is treated as there were two occurencies of that option with values formed from strings before and after that space or comma character. I.e. the following commandline strings will equally alter the behaviour of this script for option named -X:
-X a -X b -X c -X d -X 'a b' -X c -X d -X 'a b c d' -X 'a,b' -X c -X d -X 'a,b,c,d'
blah foo bar
The -U option specifies the a list of symbols that should be added to resultant set of exceptions. E.g. all the following commandline fragments request to add symbols blah, foo, bar, baz:
-U blah -U foo -U bar -U baz -U 'blah foo' -U 'bar,baz' -U 'blah foo bar baz'
Module with name $name is considered source for exceptions
if (split('::',$name))[0]
was exactly equal (i.e. charcter-by-character,
case-sensitive - in other words using eq
perl operator)
to the ones
specifed directly via -M or mentioned in file specified using -m option.
For example, specifying -M App
will make all symbols from modules
named App::Manager, App::Packer listed as exceptions, but not symbols
from modules AppConfig::MyFile and AppConfig::Std.
Module with name $name is not considered source for exceptions
if (split('::',$name))[0]
was exactly equal (i.e. charcter-by-character,
case-sensitive - in other words using eq
perl operator)
to the ones
specifed directly via -N or mentioned in file specified using -n option.
Use these options if you are sure that the code being obfuscated won't ever use symbols with these names from other modules (using these names for private variables is perfectly OK, of course) - this helps your programs to become even more obfuscated, especially if you use modules that export a lot of symbols (like e.g. Gtk::*).
The files from which it extracts exceptions should be synaxically correct, and
all modules it requires or uses should be present. If the modules the
files from which it extracts exceptions are in non-standard locations,
you should specify these locations using -p switch - e.g. to extract
exceptions from file, that uses modules located in directory lib, add
the following to your commandline: -p 'perl -Ilib'
.
It's impossible to create a list of exceptions by using only -d switch
for modules referenced using require
operator. You will have to specify
module name prefix to be able to extract symbols from such modules.
This script extracts just symbol names, without any type information - i.e.
if some module exports just two symbols - $foo and %foo, the resultant
exceptions file will contain just one line with word foo
. The strings passed
directly via -u, -x options and indirectly via files specified with
-u, -x should also be symbol names, without package name part and
without type-specific prefix ($, %, etc) - e.g. bar, not
$bar or $blah::bar (though the script will try to extract bare symbol
name).
On unix-like OSes, in case all perl source files use modules from standard locations (/usr/lib, /usr/local/lib, etc) it's very convenient to invoke the gen-ident-exceptions.pl script with the relative paths to the perl source files, adding -d / to the commandline. This way you won't have to type common module prefixes your source file uses. On Windows same applies, but appending -d C: to the commandline instead (provided the perl is installed on drive C:).