upx/README.SRC

                        The UPX Hacker's Guide
                        ======================


Foreword
--------

  The precompiled UPX versions are linked against the NRV compression
  library instead of the UCL library. Using the same compression algorithms,
  NRV achieves a better compression ratio. NRV is not publicly
  available, though, and probably never will be.

  While you may be disappointed that you don't have access to the
  latest state-of-the-art compression technology this is actually
  a safe guard for all of us. The UPX source code release makes
  it very easy for any evil-minded person to do all sort of bad
  things. By not providing the very best compression ratio it is much
  more difficult to create fake or otherwise disguised UPX versions (or
  similar trojans), as any end user will notice when the compression
  has gotten worse with a new "version" or "product".

  Finally please be aware that you now have your hands on the source
  code of the most sophisticated executable packer ever.
  Let's join our forces to make it even better :-)

  Share and enjoy,
  Markus & Laszlo


Introduction
------------

  Welcome to the UPX source code release!

  UPX is not a toy for kids. Apart from basic knowledge about executables
  and data compression you will need to be firm in C++, assembler,
  Perl and Makefiles. Probably some other things as well.

  If you can't manage to compile it then the sources are
  probably not for you. Don't email us for help.

  The authors use Linux for development. You might want to as well.


Short overview
--------------

  The UPX source code consists of two mainly independent parts:

  1) The src/stub directory contains the decompression stubs that
     will get added to each compressed executable.
     The stubs are mainly written in assembler and get "compiled"
     into ordinary C header files.

  2) The src directory contains the actual packer sources. The stubs
     are #included by the individual executable format handlers.


Prerequisites
-------------

  - first of all you need to build the UCL compression library
    http://www.oberhumer.com/opensource/ucl/


Tools needed to build/modify the UPX sources
--------------------------------------------

  - A C++ compiler supporting inner classes, templates, exceptions
    and RTTI.

  - GNU make 3.80 or better (GNU make 3.81 recommened).


To compile the packer sources
-----------------------------

  set the environment variable UPX_UCLDIR to point to your UCL installation, e.g.

     set UPX_UCLDIR=c:\src\ucl-1.03                   (DOS / Windows)
     export UPX_UCLDIR=$HOME/local/src/ucl-1.03       (Unix)

  then type

     make


If you want to modify the stub sources you'll also need
-------------------------------------------------------

  - GNU make 3.81 or better
    http://savannah.gnu.org/projects/make/

  - Perl & Python

  - A68K - a 68000 macro assembler
    http://upx.sourceforge.net/download/tools/

  - ASM5900 - a MIPS R3000 assembler
    http://upx.sourceforge.net/download/tools/

  - djasm - an assembler for the djgpp stub
    http://upx.sourceforge.net/download/tools/

  - nasm 0.98.39 - the Netwide Assembler
    http://sourceforge.net/projects/nasm/

  - Certain versions of some i386-linux tools:
       - gcc-2.95.3
       - gcc-3.4.6
       - binutils-2.16.1

  - Other cross compilers targeted at the following architectures.
       - arm-9tdmi-linux-gnu
       - powerpc-750-linux-gnu
       - x86_64-unknown-linux-gnu
    See http://upx.sourceforge.net/download/tools/ for pre-compiled
    toolchains.

  - SUMMARY:

    You will need GNU make 3.81 and the following files/symlinks in your
    ~/local/bin/bin-upx/ directory (this directory will get added to
   your $PATH automatically by src/stub/Makefile):

      bin-upx/a68k
      bin-upx/arm-9tdmi-linux-gnu-gcc-3.4.5
      bin-upx/arm-9tdmi-linux-gnu-ld
      bin-upx/arm-9tdmi-linux-gnu-objcopy
      bin-upx/arm-9tdmi-linux-gnu-objdump
      bin-upx/asm5900
      bin-upx/djasm
      bin-upx/i386-linux-gcc-2.95.3
      bin-upx/i386-linux-gcc-3.4.6
      bin-upx/i386-linux-ld-2.16.1
      bin-upx/i386-linux-objcopy-2.16.1
      bin-upx/i386-linux-objdump
      bin-upx/nasm
      bin-upx/powerpc-750-linux-gnu-gcc-3.4.4
      bin-upx/powerpc-750-linux-gnu-ld
      bin-upx/powerpc-750-linux-gnu-objcopy
      bin-upx/powerpc-750-linux-gnu-objdump
      bin-upx/sstrip                                [ from src/stub/util ]
      bin-upx/x86_64-unknown-linux-gnu-gcc-3.4.4
      bin-upx/x86_64-unknown-linux-gnu-ld
      bin-upx/x86_64-unknown-linux-gnu-objcopy
      bin-upx/x86_64-unknown-linux-gnu-objdump


Misc. notes
-----------

  As the docs say: UPX is a portable, extendable and endian neutral
  program, so if you want to add some new stuff, try not to break these
  nice properties.

  - Use the types LE16, LE32, BE16 and BE32 for fields in file headers.
  - Use [sg]et_[bl]e(16|32) for getting/setting values in the data
    stream.
  - Use gcc extensions and other compiler specific stuff only through
    macros.

***

Some conventions:

  - follow our coding style
  - indent level = 4
  - expand all tabulators

  - Use throwSomeException() functions instead of throw SomeException():
    this makes the code shorter if used often.

***

Patches/Contributions

  - Please send us bug fixes/contributions only using

      diff -u oldfile newfile

    or

      diff -uNr olddirectory newdirectory


# vi:ts=4:et