CM3 Release Candidates

This page describes the installation of the Critical Mass Modula-3 compiler and development system and its accompanying libraries, tools and application programs. As the underlying concepts are somewhat different from many other common development systems, it is advisable to read and fully understand this document before you begin the actual installation.

Here are the release notes with a summary of the changes and additions of this release.

The roadmap for release engineering and the timeline can be found in our CM3 trac instance. Here's an overview of the known problems. Finally, here are checksums for the release archives.

Just download the archives (REL and RC5). Download RC4 archives. Download RC3 archives. Download RC2 archives.

Contents

Terminology
Supported Target Platforms
Available Installation Archives
Installation Procedure
Documentation and Support Scripts RC1
Binary Distribution Archives RC1

Terminology

This section explains some of the terms that are used throughout this document. Some of them may be familiar, but in the context of CM3 they may have slightly different meanings.

Package

A package in CM3-speak is a software component of the CM3 system. Packages are divided into categories. The top-level directory of the CM3 source tree contains a lot of directories representing these categories.

Packages have explicit import and export declarations, i.e. they implement the principle of information hiding on a higher level than modules. For details on packages see Organizing software in packages from the M3 operations guide.

Packages can be local to a given user's workspace, or can be installed system-wide, so other users on the system can use them, too. Installing a package system-wide is also called shipping the package.

For example, the m3-sys category contains, among others, the packages cm3 (the compiler user interface), m3front (the compiler frontend), cminstall (the installation program), m3cc (the compiler backend) and m3quake (the Quake language interpreter).

Quake?

Yes, Quake. Although this term has been overloaded for a while by a very popular video game, CM3 stuck to the name quake for its built-in scripting language for build management (replacing the UNIX make program).

CM3 reads and understands so-called m3makefiles. These files have a similar purpose as Makefiles processed by UNIX make. This is part of the reason why installing CM3 is quite different from installing other software on a UNIX system - other software does not have make-like functionality built-in.

Target

A target is short for target platform and defines a combination of an operating system and a certain processor architecture. CM3 needs to know the details of both to work correctly. We do not consider cross-compilation here, and assume that you want to install CM3 on the target you want to run it on to produce code for the same target. An example target would be the FreeBSD operating system running on x86 processors.

Supported Target Platforms

Not all principally supported platforms or legacy targets are actually available in this release. The following table is based on a list of the currently available configuration files. Except for some legacy names, all target names have the format PROCESSOR OR ARCHITECTURE_OPERATING SYSTEM.

Available Installation Archives

This release offers

• binary archives of the central installation hierarchy and package pool (e.g. /usr/local/cm3/pkg), which are named -bin-min- and -bin-core-
• source archives of the CM3 workspace, which are named -src-
• combined binary and source workspace archives which contain parts of a precompiled user workspace, which are named -bin-ws- and may be shipped to the central package pool with the install.sh/cmd script.

You need either cm3-bin-core-*.tgz or cm3-bin-min-*.tgz for a working CM3 system. The latter is the smallest possible installation, containing only the actual compiler programs and the M3 packages m3core and libm3, while the core collection adds some useful libraries and tools which are usually needed for most purposes. This is all you absolutely need to download and install in order to use Modula-3.

In case you wonder about the names `min' and `core', they're not really accurate but legacy. We recommend to download the cm3-bin-core-*.tgz archives unless you really want something minimalistic.

Three special source archives contain parts or all the available sources of the release (though you may rather want to check these our via CVS to easily get updates). cm3-src-all-*.tgz contains the complete sources, while cm3-doc-*.tgz contains only the documentation and cm3-scripts-*.tgz contains some scripts for command line usage of CM3, which are used for maintenance and release engineering and may be useful for experienced and sophisticated users. For new users, we rather suggest to start the cm3ide program and concentrate on working on one package at at time.

The -bin-ws- archives contain package collections from a user workspace, which can easily be installed by shipping all these packages to the central package pool. If a working CM3 system is installed, these archives can be installed with the included shell script install.sh. If you want to be able to compile the source, too, you need to heed the collection dependencies documented in the description of each collection. Assuming you install cm3-bin-core and then the bin-ws collections, the topological order for the complete set in the table below is correct (which means you can install them in that order).

Here is a complete list of all available archives with detailed content descriptions:

Installation Procedure

Perform the following steps in order to install CM3 onto your system:

1. Choose the correct target platform, e.g. AMD64_LINUX or FreeBSD4. We'll call that simply TARGET from now on to identify the appropriate packages. The version part (e.g. d5.8.1-RC1) will be denoted as VERSION.
2. Decide whether you want a minimal or a standard installation; i.e. choose one of cm3-bin-min-TARGET-VERSION.tgz or cm3-bin-core-TARGET-VERSION.tgz. Download this package onto your computer. Make sure you've got enough space for unpacking the archive and installing its contents. We'll assume you chose cm3-bin-core-TARGET-VERSION.tgz from now on.
3. Unpack that archive either with POSIX command line tools or Winzip: tar -xzvf cm3-bin-core-TARGET-VERSION.tgz You should now see the CM3 installer cminstall and the system archive system.tgz.
4. Decide where you want to install your system. The default path is /usr/local/cm3. You may choose any location, including somewhere below your home directory, in case you just want to try it for yourself. We assume the default location. Run the installer as follows from the command line:
   ./cminstall /usr/local/cm3
   
   The installer also offers several options which you can list with option -h.
   
   The installation should end with the following output:

       CM3 is now installed.
   
       Before you begin, here's a few reminders:
   
         1) The CM3 compiler executable is in:
               /usr/local/cm3/bin/cm3
            You may need to modify your PATH environment variable to find it.
            And on Unix, you may need to type "rehash" to your shell.
   
         2) CM3's shared libraries and any you create and ship are in:
               /usr/local/cm3/lib
            On some Unix systems you may need to set the LD_LIBRARY_PATH
            (on Darwin / MacOS X it's called DYLD_LIBRARY_PATH)
            environment variable before running programs that use
            these shared libraries (usually not necessary).
   
         3) Your system configuration file is:
               /usr/local/cm3/bin/cm3.cfg
            At any point in time, you may edit it to modify or update your
            installation.
   
         4) A copy of this installation dialogue is in:
               /usr/local/cm3/Install.log
   
         5) If you had trouble with this installation or need more assistance,
            please send us a transcript of this installation via e-mail at
            "m3-support{at}elego.de".
           

   Follow these instructions and set the necessary environment variables appropriately. On Unix you will probably add definitions to your .profile or .bashrc scripts, while on Windows you need to set the variables via the GUI in the Computer/System Configuration settings.
   
   The basic CM3 system should now be installed. You can verify that by calling the compiler driver with as this:
   cm3 -version or cm3 -help.
5. Some words on file permissions:
   If you are using the CM3 system alone, there is nothing to be done. However, if you want to perform an installation for a group of users, you should change file access permissions as needed. CM3 does not contain any programs which need to be run with special permissions (e.g. setuid on Unix). For a shared installation, we would suggest to create a user and group m3, and let them own all the files. This can be done on Unix systems like this:
   chown -R m3:m3 /usr/local/cm3
   If you want all users of the m3 group to be able to ship packages to the central installation pool, you should set all the files to group-writable:
   chmod -R g+w /usr/local/cm3
   On Linux and System V file systems you may need to add the s mode flag to directories, too:
   find /usr/local/cm3 -type d -print | xargs chmod g+s
   Now all members of the group m3 should be able to ship M3 packages to /usr/local/cm3 as long as their UMASK is set to the appropriate 0002 (group-writable). If you only want one administrator to be able to ship packages, leave out the group-writable settings.
6. You may now choose to install additional packages, for example the CM3 development tools, containing the CM3IDE. We'll use this example for all -bin-ws- packages. First, create an empty directory for your cm3 workspace (suggested: $HOME/work/cm3) and download and unpack the archive there:
   mkdir -p $HOME/work/cm3
   cd $HOME/work/cm3
   tar -xzvf cm3-bin-ws-m3devtool-TARGET-VERSION.tgz
7. Now run the script install.sh from the command line as this:
   ./install.sh
   That's it. You can now use all the contained M3 library packages and call the installed programs, like cm3ide.

In case of problems, we suggest the following procedure:

1. Re-read all the documentation and consider if you have done something wrong.
2. If you are sure you have encountered a problem in the software, file a bug report. Be sure to add all available information, as a verbatim copy of what you have done (which commands where executed) and what results were shown (output and error messages).
3. You should also subscribe to the m3devel mailing list and discuss your problem there. This is the most likely place to find quick help.
4. Alternatively, you may write to m3-support{at}elego.de. There is a group of M3 users and developers who may be able to help. However, unless you have purchased commercial support, the m3devel list will be better as the forum there is much wider. Of course everybody will do his or her best to help you use and enjoy CM3. But please consider that this is a volunteer project and nobody gets paid for his/her support.