What is it

What's new in this version

• patch-pattern problem with 2.95.3 from "Symbian GCC Improvement Project":  Updated ForceCompilerToIncludeVariablesPatch() because the previous implementation got optimised away. Thanks to Grazvydas "notaz" Ignotas for pointing this out.
• vma fixup bug: Fixed bug resulting in incorrect relocations which can cause crashes when run on a device. Many thank to Thanks to Grazvydas "notaz" Ignotas for reporting and providing a patch for the fix.

• dll name-mangling bug: Fixed app + exe loader to allow for linking against dlls not using UIDs (resulting in dll names in the import section without name mangling).
• E32Dll fix-up bug: For dlls, the relocated address of E32Dll is used by the Symbian OS kernel as a unique key for the loaded dll. However, when using ECompXL, the kernel now knows the dll by the ECompXL's loader E32Dll address. This causes methods in class Dll to fail, particularly Dll::FileName(). This is solved by fixing-up all references to the .dll's E32Dll to ECompXL's loader E32Dll address.
  
• Checksum bug: Updated win32 tools to patch the code section in loader and recalculate the checksum over the code section. Without this fix only 1 instance of the loader code can be running at any given point in time. If two apps a1 and a2 use ECompXL than either a1 can run or a2 but not both. Because of the interoperability issuses, developers using ECompXL are strongly advised to update their apps to ECompXL 1.2.

• Search for dlls if they cannot be loaded in \system\libs on all drives and the directory from which the app/exe is run.
• Changed license from GPL to a MIT-style license.
  

Installation

1. Unzip ECompXLbin.zip (preserving the directory structure) in the top level directory of your Symbian OS development environment. For example, on my machine that directory is q:\, so Symbian OS' standard include directory is q:\epoc32\include and, after unzipping, the binaries for ECompXL are in q:\ECompXL\bin.
2. Add the ECompXL-bin directory to your PATH. On my machine that would be: q:\ECompXL\bin.
3. Rename the Symbian tool chain component epoc32\tools\petran.exe to petran_symbian.exe. Don't rename it to anything else than petran_symbian.exe, ECompXL still uses Symbian's petran.exe and relies on this name.

Verifying the installation

• If you don't see the ECompXL banner in this output then either the ECompXL-bin directory is not in your PATH or you have not renamed Symbian's petran.exe in epoc32\tools.
• If you don't see the standard Symbian petran banner then you have renamed Symbian's petran.exe but you have not correctly renamed it to petran_symbian.exe.
  

Building compressed applications and executables

• Note that ECompXL never actually sets the stack size for your component to 0x80000000. This is just used as the trigger for ECompXL to enable compression for this component.
• If you set the EPOCSTACKSIZE to 0x80000000, ECompXL sets the stack size to what ever the default is (as if you hadn't specified this statement in first place). If  you had set if to (0x80000000 + X) then ECompXL sets it to X.

Support for global data and global C++ objects in applications

• In your application's .mmp file add an USERINCLUDE statement to the ECompXL\inc directory.
• In the source file that defines your CApaApplication-derived class, add:
             #include "ECompXL.h"
  
• In the class definition for your your CApaApplication-derived class, add an object of type TECompXL. For example, hello.cpp defines it as:
             class CHelloApplication : public CEikApplication
             {
             private:     // from CApaApplication
                 CApaDocument* CreateDocumentL();
                 TUid AppDllUid() const;
                 TECompXL    iECompXL;        // support for global C++ objects
             };
  
  

• Be careful what methods your global C++ objects' constructors call. Essentially these constructors are called as part of the application's single exported method:
      EXPORT_C CApaApplication* NewApplication();
  where you create your CApaApplication-derived application object. At that point some of the Application Framework's objects already exists (such as the EikonEnv object) but are not yet fully set-up.
• Once you've taken the route to include global modifiable data and/or global C++ objects in your application (.app) you've passed the point of no return. From that moment onwards your application can only be built using ECompXL;  building it using the standard Symbian OS tool chain will fail with errors that can only be resolved by removing all global modifiable data.
• If you implement a Symbian OS application (.app) from scratch I would never recommend to just add global modifiable data or global C++ objects in this application and thus relying on ECompXL to build and run it. ECompXL currently only works for Symbian OS 7 and may not work in future versions of Symbian OS. I'd only recommend this option if you are porting legacy source code to Symbian OS and the cost of removing global modifiable data outweighs the (potential) downside of future incompatibility.
   
  

Verifying that ECompXL has compressed your .app or .exe

Performance

How ECompXL works

1. The GNU compiler (gcc.exe) compiles your source files into object (.o) files.
2. The GNU linker (ld.exe) links the object files into an intermediate executable file. The format of this executable file is called PE-COFF  which is short for Portable Executable - Common Object File Format. COFF is a file format originating from certain UN*X platforms and Microsoft has derived its WIN32  executable file format PE-COFF from it.
3. The Symbian OS tool petran.exe transforms the executable file generated by the GNU linker into an E32 executable file and this is the resulting .exe or .app file you can run on a target device.
   

1. The build process works as normal up to the point where petran.exe is called. During installation, Symbian's petran.exe was renamed to petran_symbian.exe, so rather than the original pertran.exe, ECompXL's petran.exe is called. 
2. ECompXL's petran.exe examines the -stack parameter to see if the most significant bit in this 32 bit value is set. If not, then it simply runs petran_symbian.exe with the parameters that were passed to petran.exe and the resulting executable file (.app or .exe) is the same as if ECompXL had not been installed. If this bit is set, ECompXLTran.exe is run.
3. ECompXLTran.exe starts by running PE2ECompXL.exe to generate a compressed ECompXL executable file.
1. PE2ECompXL.exe reads the intermediate PE-COFF executable file, extracts various file headers and sections, and creates an ECompXL executable file consisting of:
   
1. A single header describing all the relevant parameters for this executable (the virtual address this executable was linked for, the virtual addresses of the code, data, bss, import and relocation sections and their sizes, and the virtual address of the executable's entry point), immediately followed by;
2. the code section, immediately followed by;
3. the data section, immediately followed by;
4. the import section, immediately followed by;
5. the relocation section.
2. PE2ECompXL.exe uses gzip to compress the ECompXL executable file generated in the previous step and then exits.
   
4. ECompXLTran.exe continues and copies the ECompXL loader image ( ECompXL\bin\ECompXL.exe or ECompXL\bin\ECompXL.app for respectively .exes and .apps) to the target directory, renames it to the target executable file name and runs  petran_symbian.exe on it to ensure that parameters like UIDs, stack sizes  etc are set according to what was specified in the mmp file. ECompXL's petran.exe has passed all its parameters to ECompXLTran.exe and the exact same parameters are passed to petran_symbian.exe. Before doing so, the most significant bit in the -stack parameter is removed; if the stack size is 0 the -stack parameter is removed all together to let Symbian's petran.exe choose the appropriate default size. Since the ECompXL  loader is a normal E32 executable file, Symbian's petran.exe works as expected.
5. ECompXLTran.exe "glues" the compressed ECompXL executable file to the ECompXL loader executable file. Glueing is done by literally appending the contents of the compressed ECompXL executable file to the ECompXL loader executable file. 
6. Finally, ECompXLTran.exe appends the file offset of where the compressed ECompXL executable file got appended to the executable file.
   
   

1. The Symbian OS System Loader:
1. Reads the E32 image header from the executable file. 
2. Loads parts of the E32 executable file containing code, data, import, export and relocation sections based on information in the E32 header. Note that the Symbian OS loader doesn't just load the entire file. It only loads those parts as specified in the E32 header, which corresponds to the loader executable (roughly 10KB in size); the glued compressed executable gets completely ignored.
3. Dynamically links the E32 image in memory against dlls specified in the import section, loading dlls if needed.
4. Relocates the E32 image according to where it has been loaded into memory by applying the so called "fix-ups" from the relocation section.
5. Starts execution of the executable at its entry point, which is normally _E32Main(). _E32Main() contains Symbian OS specific start-up code such as calling constructors for global C++  objects and gets automatically included into an E32 executable file as part of the Symbian OS tool chain. _E32Main() then calls the executable's actual entry point E32Main().
   
2. After the previous step, the System Loader has finished its job and as far as it is concerned the executable is up and running. E32Main() of ECompXL's loader is now executing and does the following:
1. Opens its own executable file.
2. Seeks to the end of this file and retrieves the last 32-bit integer value; this is the file offset at which the compressed ECompXL executable file is stored.
3. Seeks to that offset and reads the GZIP header.
4. Reads the ECompXL file header and uses the ZLIB library to decompress it.
5. Creates a chunk (RChunk) for code and a chunk for data of sizes determined by information in the ECompXL file header.
6. Loads the compressed code section from file, decompresses it and stores it in the code chunk.
7. Loads the compressed data and import section from file, decompresses them and stores them in the data chunk.
8. Loads the compressed relocation section from file, decompresses it and stores it in the heap.
9. Dynamically links the executable image against libraries as specified in the import section.
10. Relocates the executable image according to where it has been loaded into memory by applying the so called "fix-ups" from the relocation section.
11. Cleans up unnecessary data structures (such as the relocation section in the heap) and calls the executable's entry point, which will normally be _E32Main(). _E32Main() performs the normal start-up code for this executable and then calls E32Main().
    

1. The ECompXL loader code is an E32 .app rather than an E32 .exe.
2. The loader code therefor starts from its first exported method (NewApplication()) which gets called by the Application Framework when the latter loads the application dll as part of application start-up.
3. The loader code, after decompressing, dynamically linking and relocating the glued compressed application, calls the first exported method in that application and returns that value from its NewApplication() entry point.
4. There is no Symbian OS start-up code in applications and therefor there is no automatic support for global C++ objects (calling their constructors and destructors). Applications created with ECompXL should therefor ensure they call constructors and destructors for global C++ objects themselves. Read the section "Support for global data and global C++ objects in applications" on how to do that.
   

Understanding ECompXL's license