Step-by-Step Guide using GUI (Project Manager)

  1. Please read Perl-Obfus: Introduction and Key Concepts.
  2. Start Project Manager
  3. Click Project ⇒ New to create new project.
    1. Enter the project input directory - a root directory where all files and subdirectories of the project already reside. It's better to have all files of your project reside there, instead of adding them later after project's creation. No files in that directory will be modified by the tool.
    2. Enter path to output directory. It's where protected version of the file will be stored. All files in your project's Input Directory that have unknown type of Perl-Obfus will be copied unmodified. It's recommended to use relative path (relative to project's Input Directory), e.g. ../outdir.
    3. For State Directory name, enter path to a directory where Perl-Obfus will store its state. The directory should exist. It's also recommended to use relative path (relative to project's Input Directory), e.g. ../statedir.
  4. Go to Project ⇒ Files to ensure the file types are detected correctly for all file types. For each file extension present in the project, it's enough to check only one file with that extension - the type of file will be in the right column.
  5. Go to Symbols ⇒ Get list of symbols from external modules, and paste it into Symbols ⇒ User-Specified exceptions.

    Do not forget to do this again when you update your code so it starts using symbol from some new third-party module.

  6. Go to Symbols ⇒ View strings encountered in code to review symbols whose names you've used in your code. Review that list. Then either copy that entire list and add it to Symbols ⇒ Edit user-specified exceptions, or alter your string constants and wrap those symbols in OBJNAME() as explained here. The later is preferred as it will result in fewer symbols being in the list of exceptions, meaning that your code will look more cryptic.
  7. Go to Build ⇒ Clear output & state files & rebuild all. Your project will be built with lite level of protection. All symbols that are subject to mangling will get ReplacementFor_ prefix prepended to them.
  8. 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 extracting symbols from that library, it probably means that extraction did not find some symbols, so you have to add them manually.
  9. Repeat 3 last steps (starting from Go to Build ⇒ Clear output & state files & rebuild all) until you get no errors while running your protected code.
  10. Go to Settings ⇒ Select preset for code mangling.. and select a production profile you wish to apply to your project and click Save. Go to Build ⇒ Clear output & state files, then do Build ⇒ Rebuild all. Then do very minor check that protected code works fine.
  11. Your product will then be ready for shipping.

Useful tips

  • If you frequently add files with code that needs to be obfuscated to your project, then instead of adding them every time using Settings ⇒ For files, you can set up how Perl-Obfus should handle unregistered files of a given file extension, by going to Settings ⇒ Edit handling of unlisted files...

    On that page, you will be asked for processing mode that should be assigned to files with a given file extension. If unsure which mode to specify, go to Settings ⇒ For files and see which mode is used for files with that file extension, and use that mode for unregistered files with that extension.

  • If you wish to make a snapshot of a project's settings (e.g. before modifying some settings), do Project ⇒ Export for backup. The generated file contains only names of files in your project and all the settings; it does not include file contents, so the file is really tiny, and it's safe to send it to your colleagues. You will be able to import the backup using Project ⇒ Import.
  • Building project using command line
    For each project, it's possible to generate a command line script (or .bat file for Windows) that will perform all operations available in Build menu. To achieve that, click on Project ⇒ Generate buildscript or Project ⇒ Generate buildscript as .bat.

    It encapsultes all your project settings because it includes a snapshot of all project's configuration, so you will have to regenerate the script every time you change the options of some modes or add or remove some files from your project (though no regeneration is necessary if you just edit set of exceptions, as settings are stored in separate file in Project's Input Directory).

    The documentation on using generated buildscripts is available here - it lists all supported command line flags.

  • If you need running obfuscator directly from command line
    go to Tools ⇒ Configure command line tools.. to install aliases to command line backends to some directory listed in your PATH environment variable. This way you won't have to type full path to command line tools. Use Tools ⇒ Command line builder to generate command lines.
  • Project Manager window is a web browser window. So you can use all common web browser shortcuts to navigate it, e.g. for going back to previous screen. On Windows, special build of Firefox is used, that talks to server via named pipes, to avoid problems with firewalls (as they prevent apps accessing even local host). You can turn off this "HTTP over named pipes" mode, and use your favourite browser to work with Project Manager.
  • You can open several windows related to your project using window operations buttons in the topmost right corner of the Project Manager window. Using them, you can clone windows. So just clone the window, then navigate to any page you need in new window. You can even open other project in new window. Of course you can also run Project Manager for different obfuscation tools too (e.g. one for JavaScript Obfuscator, one for C/C++ Obfuscator).
  • It's possible to edit a set of exceptions using your favourite editor, as it's stored in plain text file. Go to the corresponding page in the Symbols