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.
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 https://...
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).
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.
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.
If you would like to
Alternatively, continue reading the general instructions below.
Read the known problems page, especially the parts regarding CM3 5.4. You may run into one or more of the problems mentioned there while installing CM3, so it is a good idea to know about them in advance.
For this release, the following targets are supported:
| Name | Description |
| FreeBSD4 | FreeBSD 4.x and later on x86 |
| LINUXLIBC6 | Linux with glibc-6 on x86 |
| SOLgnu | Solaris 8 and later on sparc with GNU compiler |
| PPC_DARWIN | Apple's Darwin (MacOS X) system on powerpc |
| NetBSD2_i386 | NetBSD 2 and later on x86 |
To install CM3, the first thing you need is a so-called minimal binary installation archive for your platform.
The archive contains a very bare-bones cm3 installation. It contains a complete compiler and runtime libraries, but it should only be used for bootstrapping a full cm3 installation from source. A full installation contains a lot of additional tools and libraries, some of which are vital for common use.
A minimal binary installation archive is named as follows:
cm3-min-OSTYPE-TARGET-CM3VERSION.tgz.
OSTYPE is POSIX for most platforms supported by CM3.
TARGET is the target CM3 shall produce code for.
You can download a minimal binary installation archive from the download page.
As mentioned above, you also need the CM3 source code to install CM3. Several source packages are available:
cm3-src-sys-CM3VERSION.tgz
The src-sys archive contains source code for the compiler (except the compiler backend), the linker and vital core libraries.
cm3-src-gnu-CM3VERSION.tgz
The src-gnu archive contains source code for the compiler backend, which is based on the GNU C compiler, and the debugger m3gdb, which is based on the GNU debugger.
cm3-src-std-CM3VERSION.tgz
The src-std archive contains source code for a pre-defined set of standard packages that will compile and work.
cm3-src-all-CM3VERSION.tgz
The src-all archive contains the full source code for the cm3 distribution. Not all of this is needed to get a working installation. It contains experimental packages that are not compiled and installed by default, and may even be broken. It also includes everything included in other packages below. This archive is most interesting for developers who want to extend and enhance the CM3 system, or fix broken packages.
To get a complete cm3 installation, you need either the src-all archive or all three of the src-std, src-sys and src-gnu archives. If you really do not need or want the standard packages (unlikely), you could skip the src-std package.
You can download the source archives from the download page. You can verify the integrity of the downloaded archives by using the checksums and md5 hashes provided here.
WARNING: The archive unpacks into the current directory!
Once you have got the binary installation package, create a new temporary directory (for example, /tmp/cm3), change into it, and unpack the minimal binary installation archive.
Use a command like this on UNIX-like systems:
tar -zxf cm3-min-OSTYPE-TARGET-CM3VERSION.tgz
You will get the installation program (cminstall(.exe)), a copyright notice, a system archive (system.tgz) with the precompiled standard libraries m3core and libm3. You can place additional archives, e.g. the doc distribution (cm3-doc-CM3VERSION.tgz) in the same directory.
The cminstall installation program helps you setting up your initial CM3 configuration and extracts system.tgz. Alas, it is not perfect, and can be very confusing to use, especially for first-time users. There are plans to improve the installer in a future release. I will try to guide you through it as best as I can.
Change into the directory where you unpacked the archive, and start the installer by running
./cminstall
The installer will first ask you where you want to install CM3. The default installation prefix is /usr/local/cm3.
Next, it will ask about the default editor. This question is present for historical reasons. It is related to the graphical CM3 IDE called Reactor, which is not yet included in CM3. It used to be distributed with the commercial CM3 releases made by Critical Mass Inc., and was removed from the Open Source distribution because of licensing issues. There are efforts to add the IDE again in a future release. For now, you can simply ignore this question and pick the default by hitting Enter.
Next, it will ask about paths to various development tools and libaries. This is a very important part, since some packages in CM3 will not compile if these libraries cannot be found. Given the amount of targets cm3 runs on and the differences between them, we cannot give concrete examples for every possible situation. You will have to find out how to install the required tools and libraries on your system yourself. (Hint to Linux users: You may need to install library packages having a -dev or -devel suffix.)
I will elaborate a bit on what cminstall does when it asks a question, since this can be a bit confusing at first. The example output is based on the FreeBSD version, and may look slightly different on your system.
Let's consider this question cminstall is asking:
Where are the flex/bison libraries?
looking for library file(s): libfl.a
checking for library files in directory /usr/lib... found
checking for library files in directory /usr/local/lib... not found
checking for library files in directory /usr/local/gnu/lib... not found
checking for directory /usr/lib... found
1: /usr/lib
Where are the flex/bison libraries? [/usr/lib](1 of 1)
As you can see, cminstall prints the name of the library file it is looking for, libfl.a. It then searches a couple of directories for this file, and reports whether it found it. The found and not found lines are the only indicators whether cminstall was successful.
In this case, the file was only found in one directory. Hitting enter would use the default answer /usr/lib, which is displayed in square brackets, and continue with the installation. This is perfectly fine here, since the file has indeed been found in /usr/lib, as indicated by the line
checking for library files in directory /usr/lib... found
However, if cminstall cannot find the file, it behaves like this:
Where are the flex/bison libraries?
looking for library file(s): libfl.a
checking for library files in directory /usr/lib... not found
checking for library files in directory /usr/local/lib... not found
checking for library files in directory /usr/local/gnu/lib... not found
checking for directory /usr/lib... found
1: /usr/lib
Where are the flex/bison libraries? [/usr/lib](1 of 1)
As you can see, it still suggests /usr/lib as the default, even though the library was not found. Simply hitting enter now results in the following question:
The libraries libfl.a are not present in the chosen directory.
Would you like to change the library names? [yes]
Even though the default answer is yes, one would usually want to answer no here, and search the software packages available for the operating system for a package containing the needed library file. After installing the package, you can tell cminstall to try to find the library again by answering no to the next question:
Would you like to continue nonetheless? [yes]
If you answer no here, cminstall will try to find the library again. If you answer yes the default directory is entered into the configuration file and installation continues. If the library is not present in the chosen directory however, compiling the full cm3 installation will probably fail, so answering yes is usually not a really good idea (even though it is the default answer).
Next, let us consider the situation where you would have to rename a library file so cminstall can find it. This mostly applies to targets where CM3 uses shared libraries (Linux, for example). The following example uses output generated on a Fedora Core 5 Linux system.
Where are the OpenGL libraries?
looking for library file(s): libGLU.so
looking for library file(s): libGL.so libGLU.so
checking for library files in directory /usr/lib... not found
checking for library files in directory /usr/local/lib... not found
checking for library files in directory /usr/local/gnu/lib... not found
checking for directory /usr/lib... found
The output above suggests that cminstall could not find either libGL.so or libGLU.so, or both. Unfortunately, cminstall is not very smart when looking for libraries. It does not (yet) do wildcard matching on the files it is looking for. Manually searching our system, we find the following libraries in the /usr/lib directory:
[user@fedora ~]$ ls -l /usr/lib/libGL*
lrwxrwxrwx 1 root root 10 Jul 24 15:28 /usr/lib/libGL.so -> libGL.so.1
lrwxrwxrwx 1 root root 12 Jul 24 15:22 /usr/lib/libGL.so.1 -> libGL.so.1.2
-rwxr-xr-x 1 root root 389656 Jun 26 14:51 /usr/lib/libGL.so.1.2
lrwxrwxrwx 1 root root 20 Jul 24 15:22 /usr/lib/libGLU.so.1 -> libGLU.so.1.3.060402
-rwxr-xr-x 1 root root 498828 Jun 26 14:51 /usr/lib/libGLU.so.1.3.060402
So we do indeed have a libGL.so file. What is missing is a libGLU.so file. We have a libGLU.so.1 file, however. Let's use that instead, by telling cminstall that we want to rename the libraries.
checking for directory /usr/lib... found
1: /usr/lib
Where are the OpenGL libraries? [/usr/lib](1 of 1) /usr/lib
The libraries libGL.so libGLU.so are not present in the chosen directory.
Would you like to change the library names? [yes] yes
Warning: Changing the required library names is currently only partially
supported by the installer. You will have to edit /usr/local/cm3/bin/cm3.cfg
manually after the installation and adapt the -l suffixes in the SYSTEM_LIBS
array.
Sorry for the inconvenience.
The warning about having to adapt -l suffixes can be ignored in our case, since we are not renaming the library itself. We are only adding a version number.
enter library file (or ENTER to continue): libGL.so
enter library file (or ENTER to continue): libGLU.so.1
enter library file (or ENTER to continue):
Would you like to add library search paths? [yes] no
We do not need to add a search path, since cminstall is already searching /usr/lib, where our GL libraries reside.
Cminstall now suceeds:
looking for library file(s): libGLU.so.1 libGL.so
checking in directory /usr/lib... found
checking in directory /usr/local/lib... not found
checking in directory /usr/local/gnu/lib... not found
checking in directory /usr/lib... found
Cminstall found the library in /usr/lib, so the installation can continue.
When cminstall is done, update your environment so that CM3 binaries and libraries can be found by the system.
On UNIX-like systems, extend your PATH and LD_LIBRARY_PATH settings so they include CM3 binaries and libraries. Here is an example for bourne shells:
export PATH="${PATH}:/usr/local/cm3/bin"
export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/cm3/lib"
First, create a new directory for the source tree and unpack all needed source distribution archives there. Here are example commands for UNIX-like systems:
WARNING: The archives unpack into the current directory!
mkdir cm3
cd cm3
tar -zxf /path/to/cm3-src-sys-CM3VERSION.tgz
tar -zxf /path/to/cm3-src-gnu-CM3VERSION.tgz
tar -zxf /path/to/cm3-src-std-CM3VERSION.tgz
Shell scripts in the scripts/ subdirectory of the source tree can be used to build and install (or "ship") single packages or groups of packages. See the file scripts/README for details. We use a few of these scripts to bootstrap a full CM3 installation.
cd scripts ./do-cm3-core.sh buildship ./install-cm3-compiler.sh upgrade ./do-cm3-std.sh buildship
These steps take a while, especially the last one. When this is done, the installation is finished.
If the installation fails for any reason, send mail to m3-support{at}elego.de. As always, please include as much useful information as possible in your email, especially the log file written by cminstall, which resides in the installation prefix you chose, and of course hardware/operating system information.
If you want to upgrade to a new CM3 version, use the upgrade.sh script, and have a look at the chapter about upgrading.
If you are using a pre-5.3 version of cm3, a fresh install is recommended instead of upgrading. But you can also try using the upgrade-5.3.sh script instead of the upgrade.sh script.
Please have a look at the Known Problems Page. If you encounter any problem or difficulty that isn't mentioned there, don't hesitate to contact m3-support{at}elego.de, or -- even better -- file a problem report (preferably with a working fix :-)