Guide Contents Project organization Build system Working on the compiler Project organization The project directory has a README, a Makefile, and two subdirectories: documentation and source. The documentation directory contains: guide.txt This file! overview.txt A concise, high-level overview of Language 84. The source directory contains: Makefile Provides build automation, as usual. See the section "Build system" in this file for more information. *.84 Language 84 source files. support.c C code that defines the fundamental data structures and primitive functions that form the implicit basis of all Language 84 programs. 84_stable.c C code that has been generated by running the Language 84 compiler on its own source. on_programs_changed A script used by the build system. See the section "Build system" in this file for more information. program_size A script that produces a report of various size metrics for a given Language 84 program. Build system The Language 84 build system is very easy to use. Over the course of normal Language 84 programming, there is rarely any need to read or edit any Makefiles. The build process is directed by a simple plain text file, which is called "programs" and kept in the source directory. We don't check this file into the repository but rather edit it as we work. At any given time, it contains a list of the Language 84 programs that are to be built when make is invoked. For example, if the programs file contains: 84 factorial hello_world then, each time make is invoked, the compiler (84), the factorial program, and the hello_world program will be built. The dependency information that helps make determine whether a program is up to date is computed automatically by the Language 84 compiler and stored in files ending in ".c.d". There are a few configuration variables that may be used to control the build system: CC Used to select a C compiler; use either gcc or clang. OPTIM Used to select an optimization level to use while compiling generated C code. Use 0 for -O0, 2 for -O2, etc. VERBOSE The build system normally prints abbreviations of the commands it is executing. To see the commands in full, use VERBOSE=1. Note: The build process generates a fragment of make script from the programs file. The script that handles this code generation is called "on_programs_changed". The generated file is called "programs.make". Note: The details get a little more complicated when you are working on the Language 84 compiler itself instead of just using it. See the section "Working on the compiler" for more information. Note: Don't forget about the -j flag when invoking make. It can significantly reduce build times. Working on the compiler When working on the compiler, you typically build two copies of it: 84_stable and 84. The 84_stable copy is used to compile the code you are working on and the 84 copy reflects your changes and is used for testing. You work on the compiler's code just as you would with other Language 84 programs: add "84" to the programs file (as described in the "Build system" section) and use $ make 84 to build your work. To compile a program, say factorial, with the work-in-progess compiler, use: $ ./84 factorial That will create factorial.c. Then, use: $ make factorial That will use factorial.c to produce the factorial executable. You can also compare with the stable compiler by using it explicitly: $ ./84_stable factorial Once you are happy with your changes, you can make your work-in-progress compiler the new stable compiler as follows: $ ./84 84 $ cp 84.c 84_stable.c After that, if you use $ make clean ; make then your new compiler will be used for the entire build.