source: trunk/CustomizingResources.txt@ 536

Customizing FM/2 Resources

Since FM/2 is a GPL application, anyone can build a private version of
FM/2 from source and modify the program as they choose.

However, if all one wants to do is replace icons, bitmaps and text strings,
this is not required.

The FM/2 build system provides support for replacing resources without
a full rebuild from source.

== Prerequistes ==

You will need

 - a copy of the current FM/2 sources
 - a copy of the FM/2 binary release
 - a copy of the resource compiler, RC.EXE
 - a copy of the help compiler, IPFC.EXE
 - a copy of the exe compression tool, LXLITE.EXE
 - a subset of the Warp4 toolkit #include files

RC.EXE, IPFC.EXE and the #include files are included in Warp4 Toolkit which comes
with eCS or MCP.

Not all versions of RC.EXE are created equal.  Currently, the best version to
use is:

 12-18-97   6:01         868,000           0  RC.EXE

which reports itself as:

 IBM RC (Resource Compiler) Version 5.00.002 Dec 18 1997

and it is available at:

  <ftp://ftp.software.ibm.com/ps/products/warpzilla/os2tk40rc.zip>

You can get LXLITE.EXE at:

 <http://hobbes.nmsu.edu/cgi-bin/h-search?key=lxlite&pushbutton=Search>

It is recommended that you install the Warp4 toolkit.  However, if space is
tight, you only need to have RC.EXE, IPFC.EXE and the following include files
available:

  dirsize.h
  fm3.h
  fm3dlg.h
  fm3dll.h
  fm3dll2.h

== What you can change ==

In general, you can change any of the bitmaps or icons and you can make
changes to the text strings in FM3DLL.STR, FM3RES.RC or FM3RES.DLG.

When making changes to text strings, translate the _text only_.  Do _not_
reorder, remove or create new lines in FM3DLL.STR. Do not modify the
odd-looking %%s, %%lu, etc. items in FM3DLL.STR. They are used by the
formatted print routines.

When replacing icons, make sure you provide an appropriate set of
resolutions.  When replacing bitmaps, make sure you to size the bitmap to fit
correctly in place of the original bitmap.

You need to limit icons to 256 colors and 40x40 pixels.

Do not alter any other files.  If you do not follow the above guidelines,
the resource update may fail or FM/2 may refuse to run correctly.

== Installation ==

 - Create a work directory.

 - Unzip the FM/2 sources to this directory preserving
   the directory structure.

   The resulting tree will look like

    ÃÄÄfm2.work
       ÃÄÄbitmaps
       ÃÄÄdll
       ³  ÃÄÄicons
       ³  ÃÄÄinternal
       ³  ÀÄÄipf
       ³     ÀÄÄbitmaps
       ÀÄÄicons

 - Unzip the FM/2 binaries to the work directory.

 - Copy the DLLs from the the work directory
   to the dll subdirectory

 - Copy FM2RES.STR from the the work directory
   to the dll subdirectory

Alternatively, you can use your installed FM/2 binaries.

 - Copy the FM/2 EXEs to the work directory

 - Copy the FM/2 DLLs to the dll subdirectory

 - Copy FM2RES.STR to the dll subdirectory

== Verification ==

To test your setup, run:

  nmake res

from the work directory.  The makefile should run to completion without
errors.

== Customizing ==

To customize your copy of FM/2

 - Edit the resources, bitmaps and icons, as needed.

 - Apply the updates to the EXEs and DLLs with

     nmake res

   This will compile the resources, decompress the the the EXEs and DLLs and
   apply the updated resources.  The output of this process will be updated 
   versions of one or more of the FM/2 EXEs, DLLs and FM3RES.STR.  The nmake 
   is efficient and only rebuilds the files with changed content.

 - Test your updates:

     set LIBPATHSTRICT=T
     cd dll
     ..\fm3

LIBPATHSTRICT allows you to test the new FM/2 version without shutting down 
the production version.

When you are satisfied with your changes, copy the updated executable files
to your FM/2 program directory and restart FM/2.  Some of the files may be 
locked, so use the unlock.exe utility that comes with lxlite to allow these 
locked files to be overwritten.  The current command menu template includes 
unlock, so that it can be run from within FM/2. If you don't have it on your 
commands menu, I recommed you add it.

== Trouble Shooting ==

-- nmake does not rebuild the target --

nmake depends on file timestamps to know what targets to rebuild.  If you 
replace a file with an older version nmake may not do what you want it to.

One workaround is to use one of the available touch utilities, to change the 
dependent file's timestamp.

If you do not want to change the file's timestamp, use

  nmake -a res

to force all targets to be rebuilt.

$Id: CustomizingResources.txt 463 2006-09-01 00:57:36Z root $