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.