Key facts you need to know

• Please read Perl-Obfus: Introduction and Key Concepts first.
• In order to call command line interface of Perl-Obfus and other utilities shipped with it without mentioning path to those utilities, start Project Manager, go to Tools ⇒ Configure command line tools.., and specify any directory listed in your PATH environment variable there. Aliases will be installed to that directory, so you will be able to simply type perl-obfus in Terminal.
• It's VERY VERY bad idea to call perl-obfus directly! It's much more recommended to create and operate a project in Project Manager. You can build a project from command line easily: for each project, it's possible to generate a commandline script (or .bat file for Windows) that will perform all operations available via the Build menu of Project Manager (i.e. building, rebuilding and cleaning of the project) by going to Project ⇒ Generate buildscript or Project ⇒ Generate buildscript as .bat file.

  The documentation on using generated buildscripts is available here - it lists all command line flags it supports. So please go to step-by-step guide using GUI (Project Manager), and stop reading this document - as it describes inferior and old approach of using Perl-Obfus directly from command line, you can use this approach only if you have to support already existing project that uses Perl-Obfus directly via command line.

• There is nice GUI tool to generate command line using GUI, available at Tools ⇒ Command line builder. So you don't need to read documentation on command line options of perl-obfus, just use Command line builder to generate command line options.

  Also there is an online version of Command line builder here, so you can avoid starting GUI.

Step-by-step guide using command line

1. Update use of symbol names in your code mentioned in eval(), by wrapping names of symbols, into calls of OBJNAME(). See more details here.
2. Update the export tables for your modules and 'use vars' statements, as explained here.
3. Test your code, ensuring that it works fine after these changes.
4. Create a directory where files protected version of your code will be placed.
5. Create some script or Makefile that invokes perl-obfus, that handles all your files; make sure that it allows you to edit command line options applied to all invocations of perl-obfus in a single place, as you will have to run perl-obfus on your entire project several times, with different command line options
6. Create a directory named exceptions in the same directory where your code resides. You will be adding exceptions to it - a list of symbol names that should not be changed, one per line. You will store each group of exceptions to separate file, e.g. exceptions extracted automatically should go to exceptions/auto.txt, exceptions composed manually should go to exceptions/manual.txt. In order to tell perl-obfus to read exceptions from all files in that directory, append -x exceptions to perl-obfus command line.
7. Add as many libraries that your code uses into directory with your code and modify your Makefile or script so those libraries are also processed. Doing this will reduce the number of libraries that you will be generating exceptions for in the next steps.
8. Read introduction on what exceptions are.
9. Get list of symbols from external Perl modules: use gen-ident-exceptions.pl utility shipped with Perl-Obfus, like this: (command will save list of external symbols used by files 'file1.pl', 'file2.pl', 'file3.pm' to file named 'exceptions-auto.txt') - for unix (assuming you don't have any third-party modules in the directories relative to current - i.e. if all third-party modules reside in /usr/):

   	gen-ident-exceptions.pl -d / exceptions/auto.txt file1.pl file2.pl file3.pm ..
       

   for Windows (assuming you don't have any third-party modules in the directories relative to current - i.e. if all third-party modules reside in 'c:\'):

   	gen-ident-exceptions.pl -d c: exceptions/auto.txt file1.pl file2.pl file3.pm ..
       

10. Put all exceptions that were not extracted by other tools (i.e. exceptions that you've collected manually), to file named manual.txt in exceptions directory (one symbol per line).
11. Generate names of symbols that you export to other developers extacting list of symbols , store them to file named exported.txt in exceptions directory (one symbol per line).
12. Build your project with lite level of protection. To achieve this, append
    -x exceptions -i prefix -n none -s none -jam 0 -e 0
    to command line of perl-obfus generated by command line builder.

    It will produce code that is rather easy to read. All symbols that are subject to mangling will get ReplacementFor_ string prepended to them.

13. Now try to run your protected code from the output directory, testing all paths of control if possible. If you get interpreter errors like "ReplacementFor_FunctionName can't be found", most probably it means that FunctionName is a symbol from 3rd-party library. Either try to add that library to your project (so its code also gets obfuscated), or add its symbols to the list of exceptions adding symbols to exceptions by extracting its symbols extacting list of symbols . If you've already done extraction of its symbols, it probably means that extraction did not find some symbols, so you have to add them manually to file manual.txt in exceptions directory.

    You can use find-undeclared-subs.pl - utility shipped with Perl-Obfus, for finding calls of undeclared subroutines too. If your code uses use strict pragma, it will help testing a lot too, since undeclared variables will be detected at compile-time.

14. Erase all output files and repeat 2 last steps until you get no errors running your protected code.
15. Erase all output files.
16. Build your project with production level of protection. To achieve this, append
    -x exceptions
    to command line of perl-obfus generated by command line builder.
17. Perform very minor checks that protected code works fine.
18. Your product will then be ready for shipping.

If something still doesn't work, make sure you've read the recommendations in the NOTES section of the perl-obfus manual.