Index: doc/dev/getting-started.md =================================================================== --- doc/dev/getting-started.md (revision f88660877fe1fcaf02b8d8798238eaec925eafd2) +++ doc/dev/getting-started.md (revision 267b543340346faf067bb9f0fd51c75385f2ce72) @@ -27,5 +27,5 @@ ----------------- -Read and do the instructions in cfa-cc/INSTALL, to get a working CFA compiler built from source. +Read and do the instructions in cfa-cc/INSTALL, to get a working CFA compiler built from source. Many members of the core team do this (and much general work) on plg2. 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. @@ -33,14 +33,14 @@ 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 `libcfa`, the CFA core runtime library. Its source is in `cfa-cc/libcfa/src`. It gets compiled while building CFA, into `(where-ran-configure)/libcfa/x64-debug/src/.libs/libcfa.so` and `libcfathread.so`. 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. +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 into `(where-ran-configure)/libcfa/x64-debug/prelude`, which is 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: +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-cc/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 + # see cfa-cc/tests/exceptions/hotpotato.cfa: source code + # see cfa-cc/tests/exceptions/.expect/hotpotato.txt: running its ./a.out should print this Manual full test-program compilation, broken into stages: @@ -48,8 +48,8 @@ cfa test.cfa -CFA > test.lowered.c gcc -c test.lowered.c - cfa test.lowered.o # have us do the linking, to get libcfa + cfa test.lowered.o # link via our driver, to get libcfa ./a.out -Lowering step, abbreviated to be readable: +Lowering step, abbreviated to be more readable: cfa test.cfa -CFA -XCFA,-p @@ -70,8 +70,38 @@ 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): +Debugging the cfa-cpp program is most productive in a "debug" configuration. (Whereas working on libcfa changes is more productive in a cfa-cc/INSTALL "vanilla" configuration.) An example of creating such a configuration, repeating the above gdb invocation within this configuration, and doing a basic tour of cfa-cpp data structures: mkdir build-gdb cd build-gdb ../cfa-cc/configure --with-target-hosts=host:debug CXXFLAGS='-O0 -g' + make -j8 gdb -args ./driver/cfa-cpp ../test.preprocessed.cfa -p --prelude-dir ./libcfa/x64-debug/prelude + + b ResolvExpr::resolve + run + # stopped at breakpoint + fini + # in main, at the "rough halfway point" of -Pexpranly + p transUnit.decls.size() # top-level: preulde+includes+yours + set $lastDecl = transUnit.decls.back().get() # probably from your code: main? + call CodeGen::generate( $lastDecl, std::cerr ) # like -XCFA,-Pexpranly,-Pascodegen + call ast::print( std::cerr, $lastDecl, (Indenter){0,2} ) # like -XCFA,-Pexpranly + + # assuming $lastDecl is your program main, with argc/argv declared ... + p *$lastDecl # assert an ast::FunctionDecl + p ((ast::FunctionDecl*)$lastDecl)->params.size() # assert 2 + set $argc_d = ((ast::FunctionDecl*)$lastDecl)->params[0].get() + call CodeGen::generate( $argc_d, std::cerr ) + call ast::print( std::cerr, $argc_d, (Indenter){0,2} ) + + # digging into argv gives sense of AST's granularity, utility of `call print` over dig-cast-`p` + set $argv_d = ((ast::FunctionDecl*)$lastDecl)->params[1].get() + call ast::print( std::cerr, $argv_d, (Indenter){0,2} ) + p *$argv_d # assert an ast::ObjectDecl + set $argv_t0 = ((ast::ObjectDecl*)$argv_d)->type.get() + p *$argv_t0 # assert an ast::PointerType + set $argv_t1 = ((ast::PointerType*)$argv_t0)->base.get() + p *$argv_t1 # assert an ast::PointerType + set $argv_t2 = ((ast::PointerType*)$argv_t1)->base.get() + p *$argv_t2 # assert an ast::BasicType + p ((ast::BasicType*)$argv_t2)->kind # assert ast::Char