This paragraph aims to show what is needed to build cRexx from scratch. Not only the \crexx{} Virtual Machine will be built, but also the compiler, the assembler, and the \crexx{} packer, which enables building native executables on different instruction set architecture/operating system combinations.

Currently cRexx is known to build on Windows, macOS and Linux[^1]. You need one of those and:

[^1]: There is a separate instruction for VM/370 (and later) mainframe operating systems.

On Linux and macOS, this instruction is identical. For macOS, Xcode batch tools need to be installed, which will provide you with git, make and the compiler. Brew will give easy access to regina-rexx[^2] and Ninja-build.

[^2]: ooRexx and brexx will also work, one of those needs to be on the path. For Linux, you will need to install git (which will be there on most distributions), cmake and gcc or clang.

On Windows, you will need a compatibility layer like msys - installing this has the additional advantage of easy access to git, gcc, cmake and the rest of the necessary tools. On more modern Windows, the WSL[^3] and Ubuntu is not a bad choice.

[^3]: WSL: Windows subsystem for Linux.

Here it is assumed that all tools are installed and working, and available on your PATH environment variable.

Choose or make a suitably named directory on your system to contain the source code. Note that the cRexx source is kept in a different directory on you system than where it is built in, or will run from. Now run this command:

git clone https://github.com/adesutherland/CREXX.git

This will give you a CREXX subdirectory in the current directory, containing the source of cRexx and its dependencies. This is the 'develop' branch, which is the one you would normally want to use. All of these are written in the C99 version of the C programming language, which should be widely supported by C compilers on most platforms.

Make a new subdirectory in the current directory (not in CREXX, but in the one that contains it), like `crexx-build'.

mkdir crexx-build

and cd into that directory. Now issue the following command (we assume that you installed ninja, otherwise subsitute 'make' for the two instances of 'ninja'):

cmake -G Ninja -DCMAKE_BUILD_TYPE=Release ../CREXX && ninja && ctest

This will do a lot of things. In fact, if all goes well, you will have a built and tested cRexx system.

Let's zoom in a little on what we did. The first step is to tell CMake to validate your system environment and generate a build script (and a test script) for the chosen build tool. Cmake will read the file CmakeLists.txt and validate that your system can do what it asks it to do. This can yield error messages, for example if the C compiler lacks certain functions or header files. (When that happens, open an issue and someone will have a look at it - or peruse stack overflow which is what we probably also will do).

After CMake has successfully validated the build environment, it will generate a build script (a Makefile in the case of Make and a build.ninja file in the case of Ninja). This is specified after the '-G' flag. The '-DCMAKE_BUILD_TYPE=Release' flag makes sure we do an optimized build, which means we specify an '-o3' flag to the C compiler, which then will spend some time optimizing the executable modules, which makes them run faster (they do!). The alternative is a 'debug' build which will yield slower executables, but with more debugging information in them.

The two ampersands (&&) mean we do the next part only if the previous step was successful. This is a 'ninja' statement, which will build everything in the build.ninja specification file. These are a lot of parts, and the good news is, when they are built once, only the changed source will be built, which will be fast.

After this, the generated test suite is run with the 'ctest' command. This knows what to do, and will show you successes and failures. If what you checked out if git is not a released version, there is a small change that some test cases fail, but generally these should indicate success.

Rexx code is used twice during the build process. The first time is in an early stage: as the Rexx VM 'machine code' instructions are generated from a file, a Rexx script needs to work on these to generate two C sources. (The Rexx engine for this needs to be in working order on the building system - this is one of the things CMake checks, and it can flag down the build if it cannot locate a working 'rexx' executable).

The second time Rexx is used, it is already our working cRexx instance: the library of built-in functions is written in Rexx (and Rexx Assembler) and needs to be compiled (carefully observing the dependencies on other Rexx built-in functions) before it is added to the library and the cRexx executables.

When all went well, we have a set of native executables for the platform we built cRexx on. These are

You read that right, cRexx already can compile your Rexx script into an executable file, that can be run standalone, for example, on a computer that has no cRexx and/or C compiler installed.

Another salient fact from the above table is that 'rxdb', the cRexx debugger, is entirely written in Rexx and compiled and packaged into an executable file.

The executables in the above table need to be on the PATH environment variable. These are to be found in the compiler, assembler, disassembler, debugger and cpacker directories of the crexx-build directory we created earlier. It is up to you to add all these separately to the PATH environment, or to just collect them all into one directory that is already on the PATH.