OmniMake Installation Instructions
Last modified November 17th, 1997 - luke

I've tried to make the installation and configuration instructions for OmniMake as clear as possible. However, the build system is innately complex, with a multitude of trouble spots, especially considering the differences in all the supported OPENSTEP platforms. Should you find errors in any of these instructions, or feel that a particular segment could be presented better, please send your feedback to omnimake@omnigroup.com. We've also created a mailing list for OmniMake users to help each other. For instructions on how to join the OmniMake-users mailing list, see http://www.omnigroup.com/MailArchive/

1. Unpack the OmniMake source distribution.

   Unpack the OmniMake distribution package, or checkout OmniMake from the OmniGroup source repository, if available. Once unpackaged, you should have a single directory, "OmniMake", which contains everything you'll need to use OmniMake except a working installation of perl.

   Move the "OmniMake" directory to the final location where you want the OmniMake system installed. This path will be your OMNIMAKE_ROOT. We store OmniMake in ~/Source/OmniGroup where ~/Source is a symbolic link to a location on each developer's local disk. Larger sites might wish to use /LocalDeveloper, or similar, as their OMNIMAKE_ROOT and let all their developers share a single copy of OmniMake.

2. Install OmniMake utility scripts.

   OPENSTEP Mach
     1. Copy $OMNIMAKE_ROOT/utilities/nextstep/omnimake to a location in your shell PATH. We use /usr/local/bin.
     2. Copy $OMNIMAKE_ROOT/utilities/nextstep/zomnimake to /usr/local/etc if you want the various settings in this file to be site-wide. You can also create a custom .zomnimake in your $HOME directory and OmniMake will source that at run-time.
   PDO/Solaris
     1. Copy $OMNIMAKE_ROOT/utilities/nextstep/omnimake to a location in your shell PATH. We use /usr/local/bin.
     2. Copy $OMNIMAKE_ROOT/utilities/nextstep/zomnimake to /usr/local/etc if you want the various settings in this file to be site-wide. You can also create a custom .zomnimake in your $HOME directory and OmniMake will source that at run-time.
   OPENSTEP Enterprise (Windows NT)
     1. Copy $OMNIMAKE_ROOT/utilities/winnt/omnimake to a location in your System PATH. We add $OMNIMAKE_ROOT/utilities/winnt to our System PATH directly.
   It is expected that you have perl5 installed with the perl binary in your PATH. Omni has a compiled distribution of perl5 available for Windows NT if you need it, though it isn't distributed with OmniMake directly for size considerations.

3. Install Makefile patches.

   Patching the OPENSTEP Makefiles is only required on NT, since certain problems with the original Makefiles couldn't be circumvented through the LOCAL_MAKEFILEDIR hook.

   Before patching any Makefiles shipped with OPENSTEP Enterprise, be sure to make a backup copy of your $NEXT_ROOT/NextDeveloper/Makefiles/pb_makefiles directory. If for some reason you lose your backup copy of the Makefiles, and patching causes problems, you'll probably have to reinstall OPENSTEP Enterprise.

   After backing up your pb_makefiles directory, apply the Makefile patches at $OMNIMAKE_ROOT/utilities/winnt/pb_makefiles.patch to your $NEXT_ROOT/NextDeveloper/Makefiles/pb_makefiles directory. Since OPENSTEP Enterprise doesn't come with a version of patch.exe, we've put a compiled version on our OmniMake web page, at http://www.omnigroup.com/DeveloperResources/OmniMake. This version of patch relies on the Cygnus win32gnu.dll, which is also included. You apply the patch by executing the following in your $NEXT_ROOT/NextDeveloper/Makefiles/pb_makefiles directory:

           patch < $OMNIMAKE_ROOT/utilities/winnt/pb_makefiles.patch

   Please note that win32gnu.dll must be in your PATH for patch.exe to work properly.

4. Set shell environment variables.

   The OmniMake build system was designed to be as flexible as possible. If you're satisfied with the default behavior of the system, you can use it without setting any environment variables. However, if you need to tailor OmniMake for your site, you can do so by adjusting the values of the following variables.

   Special Note For NT: In order for the defaults to work properly you must be sure that $USER and $HOME are defined. These variables are defined automatically by most Unix shells, but you must explicitly set them under Windows NT. Also, when specifying paths under Windows NT, you should use the forward-slash character, "/", as your path separator.

   OMNIMAKE_ROOT
     This variable defines the root location of your OmniMake tree. The Makefiles and utilities directories are expected to be immediate children of this directory.

     Default:

         OMNIMAKE_ROOT=$HOME/Source/OmniGroup/OmniMake

     NT-Only Default:

         OMNIMAKE_ROOT=Z:/$USER/Source/OmniGroup/OmniMake

   OMNIMAKE_BUILD_OUTPUT_ROOT
     This variable defines the root location of your build output tree. Build output consists of derived source, object files, and product binaries. The build output tree is organized so that each project type is in its own subdirectory, and each project exists within a unique subdirectory below that.

     Default:

         OMNIMAKE_BUILD_OUTPUT_ROOT=/Cache/$USER/BuildOutput

     NT-Only Default:

         OMNIMAKE_BUILD_OUTPUT_ROOT=$NEXT_ROOT/../Cache/$USER/BuildOutput

   OMNIMAKE_INSTALL_ROOT
     This variable defines the root location of your trimmed build output tree. This tree is organized much like OMNIMAKE_BUILD_OUTPUT_ROOT in that there exists a directory for each individual project type, but differs in that each product exists directly below its project type directory. Because of this, object files and derived source, which are unnecessary for the final product, are left out. On Mach, OMNIMAKE_INSTALL_ROOT products are often symbolic links to their OMNIMAKE_BUILD_OUTPUT_ROOT counterparts. On NT, copies are made.

     In practice, you should be able to tar up, or package built projects from their OMNIMAKE_INSTALL_ROOT locations and distribute them as the final, installable, product.

     Default:

         OMNIMAKE_INSTALL_ROOT=/Cache/$USER/InstallRoot

     NT-Only Default:

         OMNIMAKE_INSTALL_ROOT=$NEXT_ROOT/../Cache/$USER/InstallRoot

   The method you use to customize your environment variables varies slightly depending on what platform you're using. Explanations for each platform follow:

   OPENSTEP Mach
     To customize the environment variables described above, set the value of each variable in your /usr/local/etc/zomnimake or $HOME/.zomnimake (assuming you're using zsh), like so:

     export OMNIMAKE_ROOT=Path to your OmniMake directory
     export OMNIMAKE_BUILD_OUTPUT_ROOT=Path to output build products
     export OMNIMAKE_INSTALL_ROOT=Path to output trimmed build products

   PDO/Solaris
     To customize the environment variables described above, set the value of each variable in your /usr/local/etc/zomnimake or $HOME/.zomnimake (assuming you're using zsh), like so:

     export OMNIMAKE_ROOT=Path to your OmniMake directory
     export OMNIMAKE_BUILD_OUTPUT_ROOT=Path to output build products
     export OMNIMAKE_INSTALL_ROOT=Path to output trimmed build products

   OPENSTEP Enterprise (Windows NT)
     Since OPENSTEP Enterprise uses bourne shell, rather than zsh, we created an equivalent to the zsh 'zshenv' mechanism. If you were to set OmniMake variables in your profile.sh, you'd likely discover that other profile.sh'isms, such as "set -E emacs", conflict with gnumake.

     Put the following in your $HOME/profile.sh (assuming SHENV is defined to be $HOME/profile.sh)

         . $HOME/.omnimake

     (This causes sh to source your $HOME/.omnimake with each subshell).

     Set the following in your $HOME/.omnimake, like so:

     export OMNIMAKE_ROOT=Path to your OmniMake directory
     export OMNIMAKE_BUILD_OUTPUT_ROOT=Path to output build products
     export OMNIMAKE_INSTALL_ROOT=Path to output trimmed build products

     Since OPENSTEP Enterprise is by far the most difficult platform to configure OmniMake on, I'm including examples of valid profile.sh, and .omnimake files, as well as an example System PATH from a working OmniMake installation.

     Example $HOME/profile.sh:

         #!sh

         alias ls='ls -FC'
         alias ll='ls -l'
         alias clear='cls'

         set -E emacs
         export PS1='vroom-nt \w: '

         . $HOME/.omnimake

     Example $HOME/.omnimake:

         export OMNI_SOURCE_ROOT=Z:/luke/Source/OmniGroup
         export OMNIMAKE_BUILD_OUTPUT_ROOT=D:/Cache/luke/BuildOutput
         export OMNIMAKE_INSTALL_ROOT=D:/Cache/luke/InstallRoot

     Example System PATH:

         D:\NEXT\SYBASE\DLL;D:\NEXT\NEXTDEVELOPER\EXECUTABLES\UTILITIES;D:\NEXT\NEXTDEVELOPER\EXECUTABLES;D:\NEXT\NEXTLIBRARY\EXECUTABLES;%SYSTEMROOT%\SYSTEM32;%SYSTEMROOT%;D:\NEXT\NEXTLIBRARY\JDK-1_0_2\BIN;D:/Cache/luke/InstallRoot/Executables;Z:/luke/Source/OmniGroup/utilities/winnt;Z:/luke/Source/OmniGroup/utilities/winnt/perl5/bin

5. Build OmniMake support programs.

   OmniMake uses three compiled tools during the build process: projectInfo, dictionaryKeys, and mergeDictionaries. These tools must be built before anything else. A global Makefile has been provided in the "utilities" directory to build each of the tools in turn.

   From a shell, simply go to $OMNIMAKE_ROOT/utilities and type:

       omnimake

   For descriptions of each of the tools look for documentation in the "utilities" directory, and in each of the project directories themselves, below "utilities".

6. Build ProjectBuilder convenience bundles.

   For OmniMake to work properly with ProjectBuilder, a few PB variables must be set for each project using the system. We provide a bundle to automatically do this, when a project is created or opened (and has the wrong information). Using the bundle isn't strictly required, but it does automate several redundant tasks, so most of us use it. The bundle source is located at: $OMNIMAKE_ROOT/PBBundles/PBDefaultBuildTool. Build PBDefaultBuildTool with omnimake from the command-line, and add the resulting bundle product to your ProjectBuilder bundle preferences. Quit and restart PB. Now when you open a project, you are given three choices:

   1. Reset the PB variables to the omnimake scheme, if they're incorrect.
   2. Keep the old values and don't ask about this project again.
   3. Don't do anything, but ask again on next load.

   For a more detailed description of PBDefaultBuildTool.bundle see the documentation in $OMNIMAKE_ROOT/PBBundles.

Hopefully at this point you've successfully installed OmniMake! Now sit back, relax, and enjoy a build environment with fewer bugs (hopefully), cool organization, and far too much perl for its own good.