Getting Set Up as a CFA Developer
=================================


Joining the Core Team
---------------------

If you are a new student on Peter Buhr's research team (or playing a similar "embedded" role), you need to ensure that Peter provides you with membership/access for:
  - ssh login on plg2.uwaterloo.ca
  - push to the git repo cforall@plg.uwaterloo.ca:software/cfa/cfa-cc
  - log in to the bug tracker (to create/edit tickets that are publicly browsable): https://cforall.uwaterloo.ca/trac
  - receive email notifications for git pushes, ticket edits, and build successes/failures
  - receive email broadcasts of the broader PLG: proglang-research@lists.uwaterloo.ca

Note also the resources:
  - projet's public website: https://cforall.uwaterloo.ca/
  - common build service, publicly browsable: https://cforall.uwaterloo.ca/jenkins/
    - It orchestrates build+test on a dozen machines of varying architectures
    - It runs a ~10-min build+test after every push and emails the result
    - It runs a ~1-hour build+test nightly (plus, upon request to Peter) and emails the result
    - It's normal to push a change that was working locally, but have these more thorough tests tell you otherwise.  No shame in "breaking the build," just get it fixed.  (Usually, roll back your change if a fix will take more than a couple hours, but case-by-case discussion is common.)
    - When more info about a failure is needed than what's in the log attached to the email, it's often findable by browsing the Jenkins website
  - Direct email from you to all individuals in the core team is the best way to ask how something works, what an error message means, or so on.


Kicking the tires
-----------------

Read and do the instructions in cfa-cc/INSTALL, to get a working CFA compiler built from source.

The program `cfa` is the driver, which acts like a command-line stand-in to the `gcc` command.  Its source starts from cfa-cc/src/driver/cfa.cc.

The driver runs `cfa-cpp`, which is the actual Cforall to C transpiler, while cfa is a wrapper command which runs the preprocessor, cfa-cc, and then the rest of the gcc compilation chain. The `cfa-cpp` source code starts from cfa-cc/src/main.cpp.

Most CFA programs rely on `libcfa`, the CFA core runtime library.  Its source is in cfa-cc/libcfa/src.  It gets compiled while building CFA.  Your test programs link with it.

Most CFA programs rely on "the prelude", which is a collection of headers that your test programs implicitly import.  Its source is in cfa-cc/libcfa/prelude.  It gets preprocessed while building CFA, and the result is compiled within your test programs.

A variety of example CFA programs is available in cfa-cc/tests/**/*.cfa.  They compile and run in a test-suite invocation as described in cfa-cf/INSTALL, as occurs under a Jenkins build, or as some prefer to run manually:
    pwd # assert in a build folder
    ./tests/test.py --all -j8
    ./tests/test.py exceptions/hotpotato # just one test
      # cfa-cc/tests/exceptions/hotpotato.cfa: source code
      # cfa-cc/tests/exceptions/.expect/hotpotato.txt: running its ./a.out should print this

Manual full test-program compilation, broken into stages:

    cfa test.cfa -CFA > test.lowered.c
    gcc -c test.lowered.c
    cfa test.lowered.o  # have us do the linking, to get libcfa
    ./a.out

Lowering step, abbreviated to be readable:

    cfa test.cfa -CFA -XCFA,-p

Example of examining the CFA lowering at roughly its halfway point:

    cfa test.cfa -CFA -XCFA,-p,-Pascodegen,-Pexpranly

-XCFA passes the argument/comma separated arguments to cfa-cpp.  Get help on more -XCFA/cfa-cpp arguments:

    cfa test.cfa -CFA -XCFA,--help
    cfa-cpp --help

Example of isolating a cfa-cpp invocation on your test program.  Most useful for debugging the code under `cfa-cc/src`.  The presentation assumes an install in the style that cfa-cc/INSTALL calls "side-by-side," though there are equivalents for all the styles.

    ./build/driver/cfa test.cfa -E > test.preprocessed.cfa
    ./build/driver/cfa-cpp test.preprocessed.cfa -p --prelude-dir ./build/libcfa/x64-debug/prelude
    gdb -args ./build/driver/cfa-cpp test.preprocessed.cfa -p --prelude-dir ./build/libcfa/x64-debug/prelude

Debugging the cfa-cpp program is most productive in a configuration purpose-build for it.  (Whereas, working on libcfa changes is more productive in a cfa-cc/INSTALL "vanilla" configuration.)  An example of creating such a configuration, and repeating the above gdb invoation within this configuration (again, in the side-by-side style):

    mkdir build-gdb
    cd build-gdb
    ../cfa-cc/configure --with-target-hosts=host:debug CXXFLAGS='-O0 -g'
    gdb -args ./driver/cfa-cpp ../test.preprocessed.cfa -p --prelude-dir ./libcfa/x64-debug/prelude