Index: INSTALL =================================================================== --- INSTALL (revision 329c62fc59e295a2bdd4d95b0e39ef10aaf38b0d) +++ INSTALL (revision d6c59bce0af34706acc419cc2da88d01f9b2d2c9) @@ -11,4 +11,5 @@ $ ./configure [ --prefix=/some/directory ] $ make -j 8 install + $ cfa For users using the distributed tarball / github: @@ -16,6 +17,21 @@ $ ./configure $ make -j 8 install + $ cfa where 8 is the number of CPUs on your computer. + +The above instructions produce an in-tree, installed build, where intermediate +binaries share the same folders as their sources, and where the final result +becomes an "official" CFA version for the current environment. For developers +preferring an isolated side-by-side build, where all binaries are separated +from sources, where it is possible to build multiple configurations from a +common set of sources, and where no "official" CFA version is designated: + + $ ./autogen.sh + $ mkdir ../build + $ cd ../build + $ ../cfa-cc/configure + $ make -j 8 + $ ./driver/cfa Index: doc/dev/README =================================================================== --- doc/dev/README (revision d6c59bce0af34706acc419cc2da88d01f9b2d2c9) +++ doc/dev/README (revision d6c59bce0af34706acc419cc2da88d01f9b2d2c9) @@ -0,0 +1,1 @@ +These documents provide instructions for CFA developers. Index: doc/dev/getting-started.md =================================================================== --- doc/dev/getting-started.md (revision d6c59bce0af34706acc419cc2da88d01f9b2d2c9) +++ doc/dev/getting-started.md (revision d6c59bce0af34706acc419cc2da88d01f9b2d2c9) @@ -0,0 +1,77 @@ +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