# Installation

The latest version of PM3 may be obtained from m3.polymtl.ca by WWW (or FTP in subdirectories pkg, bootstrap, binaries, SRPMS).

## RPM installation

For LINUXLIBC6, RPM source and binary packages are available and may conveniently be installed with the `rpm` program. This way, for most cases, nothing special (e.g. setting environment variables) should be required. It should be noted however that the default INSTALL_ROOT for RPM packages is `/usr` instead of `/usr/local/pm3`, thus for instance, in the installation instructions, directory /usr/local/pm3/lib/m3/TARGET in fact refers to /usr/lib/m3/TARGET.

## Binary Installation

A binary distribution of PM3 contains executable programs, libraries, and run time data files (scripts, bitmaps, document type definitions...). It comes in a tar compressed file and may be untarred from the root directory. As explained below, you need to set appropriately the PATH environment variable, and possibly the LD_LIBRARY_PATH environment variable on some of the platforms supporting shared libraries.

In the examples below, TARGET refers to the platform name and should be replaced by LINUXELF, SPARC, SOLgnu... depending on your target platform, and version refers to the PM3 version.

The PATH environment variable must contain the directory where the executable programs reside, typically /usr/local/pm3/bin. On platforms with shared libraries (dynamically linked), the dynamic linker must find the shared libraries along its path. Typically, the LD_LIBRARY_PATH environment variable will need to include /usr/local/pm3/lib/m3/TARGET. For some platforms (LINUXELF, SPARC, SOLgnu), the shared libraries paths are specified at link time and LD_LIBRARY_PATH need not contain anything, if the shared libraries are at the location specified at link time. Be careful not to have LD_LIBRARY_PATH point to older versions of the PM3 libraries, which is likely to cause problems for executing PM3 programs.

Some programs require data files at run time. The locations for these files may be specified as a command line option for the program. Default locations use the values specified in the m3config library. These values reflect the compiler configuration templates at the time m3config was compiled. For the compiler itself (m3build and m3ship), a more elaborate scheme is used to find the templates. A command line option may be set (`-T path`), the `M3TEMPLATES` environment variable may be specified, and the m3config library values serve as default location. Failing that, the `PATH` environment variable is used to locate `m3build` and the templates are assume to be reachable from there using the relative path `../lib/m3/pkg/m3config/src`. Because of this, the compiler finds automatically the templates in most cases, and the installation may look like (the ftp transfer is only needed if you dont use the simpler WWW download menu):

    cassis> cd
    cassis>ftp m3.polymtl.ca
    ftp> binary
    ftp> cd pub/m3/binaries/TARGET
    ftp> ls
    ftp> cd version
    ftp> get usr.tgz
    ftp> quit
    cassis> cd /
    cassis> tar xpfz ~/usr.tgz
    cassis> rm ~/usr.tgz
    cassis> setenv PATH /usr/local/pm3/bin:${PATH}
    cassis> setenv LD_LIBRARY_PATH \
    > /usr/local/pm3/lib/m3/TARGET:${LD_LIBRARY_PATH}
    cassis>

In rare cases, (e.g. if the system libraries are at an unusual location), you may need to modify the templates in order to reflect your system configuration. This is achieved by examining the content of /usr/local/pm3/lib/m3/pkg/m3config/src/COMMON and overriding the improper variables and functions in the platform specific template /usr/local/pm3/lib/m3/pkg/m3config/src/TARGET.

## Source only Installation

For a source only distribution, you need a compatible version of m3build and m3ship already installed. The PATH and LD_LIBRARY_PATH environment variables also need to be set properly as explained in the previous section. You may then customize the compiler configuration files in m3config/src, select the packages to compile in src/PACKAGES, and then proceed with the compilation and installation (`m3build`). Typically the source is downloaded through the WWW download menu, and the ftp transfer may be omitted from the following procedure.

    cassis> cd
    cassis>ftp m3.polymtl.ca
    ftp> binary
    ftp> cd pub/m3/pkg
    ftp> ls
    ftp> get version.tgz
    ftp> quit
    cassis> tar xpfz version.tgz
    cassis> rm version.tgz
    cassis> setenv PATH /usr/local/pm3/bin:${PATH}
    cassis> setenv LD_LIBRARY_PATH \
    > /usr/local/pm3/lib/m3/TARGET:${LD_LIBRARY_PATH}
    cassis> cd version
    cassis> m3build

## Bootstrap Source Installation

The bootstrap for a platform contains the assembly source for all the files comprising m3build and m3ship, and suitable makefiles. The PATH and LD_LIBRARY_PATH environment variables need to be set properly as in the previous sections. You may then customize the top level bootstrap makefile `Makefile` if needed, customize the compiler configuration files in m3config/src, select the packages to compile in src/m3makefile, and then proceed with the compilation and installation (`make`). The WWW download menu allows one to download the bootstrap and source as a single file.

    cassis> cd
    cassis>ftp m3.polymtl.ca
    ftp> binary
    ftp> cd /pub/m3/pkg
    ftp> ls
    ftp> get version.tgz
    ftp> cd /pub/m3/bootstrap/TARGET
    ftp> get version.tgz boot.tgz
    ftp> quit
    cassis> tar xpfz version.tgz
    cassis> tar xpfz boot.tgz
    cassis> rm version.tgz boot.tgz
    cassis> setenv PATH /usr/local/pm3/bin:${PATH}
    cassis> setenv LD_LIBRARY_PATH \
    > /usr/local/pm3/lib/m3/TARGET:${LD_LIBRARY_PATH}
    cassis> cd version
    cassis> make

## Calling the correct support tools

Users with non-standard environments may encounter installation problems, and must take special care to ensure that the necessary tools (C compiler, assembler, etc.) are correctly located by the boot `Makefile`. This warning applies especially to Solaris users, since the Sun C compiler is sold and installed separately from other systems tools, and hybrid Solaris/GNU environments seem to be fairly common.

In general, the machine's native assembler, C compiler, and "make" must be used in preference to GNU's. Obvious exceptions are the Linux versions, for which "native" means "GNU"; and the SOLgnu version, for which one must use the native assembler together with GNU's `gcc` and `make`.

Users should therefore prune their command directory list (`$PATH` in most shells) to the bare minimum, making sure that the native command directories appear before alternative ones (such as GNU's). In particular, the `$PATH` must not include any previous Modula-3 installation. Also, the shell environment variables `$AS`, `$CC`, and `$MAKE` should be set to the absolute pathnames of the corresponding executables. By the same token, all program names specified in the template file (`"m3config/src/platform`) should be absolute pathnames.