Oil Dev Cheat Sheet - oilshell/oil GitHub Wiki

The Contributing page walks you through the dev tools.

Here is a list of commands I often run.

IMPORTANT: source devtools/completion.bash gives you completion for the "two level structure" of shell files and functions. You can hit tab and then it will complete function names. (TODO: There is some flakiness if you hit tab in the wrong place, but it generally works. #797).

Install Deps

build/deps.sh fetch
build/deps.sh install-wedges  # creates /wedge and ~/wedge

build/deps.sh rm-oils-crap  # if you want to start over, removes /wedge and ~/wedge

3 Step Build

First you have to get dependencies, which is described on the Contributing page. Example: deps/from-tar.sh layer-re2c.

Then here is the normal loop:

build/py.sh all           # now interpreted bin/osh and bin/oil are ready
./NINJA-config.sh         # crawl Python deps and write build.ninja
ninja _bin/cxx-dbg/osh    # or any other Ninja target

Oil Ninja Build

When should I rebuild?

In general, whenever you git pull, or switch branches, you should re-run:

build/py.sh all
./NINJA-config.sh

(If that doesn't work, you may also want to build/clean.sh.)

Details

Oil in Python

build/py.sh all  # create the Python dev build

bin/osh -c 'echo hi'  # directly run dev build

bin/ysh -c 'cd /tmp { echo hi }'  # dev build of YSH


test/unit.sh all  # run all Python unit tests

test/spec.sh smoke  # run a single test suite

test/spec.sh smoke -r 0 -v  # run a single test 

test/spec-py.sh osh-all  # run all OSH spec tests

test/spec-py.sh ysh-all  # run all YSH spec tests

build/clean.sh  # remove files created by build/py.sh all

Static Checks

devtools/types.sh check-oils  # check the Oils codebase

devtools/types.sh soil-run

test/lint.sh soil-run

Reformatting Python:

devtools/format.sh install-yapf  # install a specific version that we need to agree on

devtools/format.sh yapf-known  # format all files we care about - SLOW

devtools/format.sh yapf-changed  # better: make sure everything is committed on your branch,
                                 # it only auto formats what's changed

devtools/format.sh yapf-files osh/cmd_eval.py  # select specific files

Reformatting C++

# download and extract Clang (used for coverage and auto-formatting)
deps/from-binary.sh download-clang
deps/from-binary.sh extract-clang

devtools/format.sh all-cpp  # reformat the C++ code.  'git diff' to see the result.

oils-for-unix (C++)

build/py.sh all  # must build Python before building C++

./NINJA-config.sh  # generate build.ninja

ninja _bin/cxx-dbg/osh

_bin/cxx-dbg/osh -c 'echo hi'  # directly run oil-native

ninja _bin/cxx-opt/osh  # optimized version

# run unit tests in these dirs
asdl/TEST.sh unit
cpp/TEST.sh unit

# Run all C++ unit tests
test/cpp-unit.sh all-tests

# run individual tests with a specific build variant

ninja _bin/cxx-asan/cpp/core_test && $_
ninja _bin/cxx-ubsan/cpp/core_test && $_
ninja _bin/cxx-gcverbose/cpp/core_test && $_


test/spec-cpp.sh run-file smoke  # run a single suite against oil-native

test/spec-cpp.sh run-file smoke -r 0 -v  # as above

test/spec-cpp.sh run-file smoke -r 0 -p > _tmp/0.sh  # print code to file
_bin/cxx-dbg/osh _tmp/0.sh                               # run it directly
gdb --args _bin/cxx-dbg/osh _tmp/0.sh                    # debug it directly

test/spec-cpp.sh all  # run all OSH tests with C++


build/clean.sh  # cleans the C++ build too

mycpp

mycpp/TEST.sh test-runtime   # run the unit tests

mycpp/TEST.sh test-translator  # compare mycpp/examples, includes "ninja mycpp-logs-equal"

ninja -j 1 mycpp-logs-equal  # sometimes useful to run serially and isolate failure

ninja -t targets all | sort  # list hundreds of targets (variants).  Use with grep.


PYTHONPATH=.:mycpp mycpp/examples/parse.py           # run python example directly
ninja _bin/cxx-asan/mycpp/examples/parse.mycpp       # make sure C++ translation is up to date
_bin/cxx-asan/mycpp/examples/parse.mycpp             # run C++ translation 

# shell trick I use to automate the above
ninja _bin/cxx-asan/mycpp/examples/parse.mycpp && $_   # $_ runs last arg as command

BENCHMARK=1 _bin/cxx-opt/mycpp/examples/parse.mycpp  # run optimized binary in benchmark mode

_bin/cxx-testgc/mycpp/gc_stress_test               # run an individual test
_bin/cxx-testgc/mycpp/gc_stress_test -t test_foo   # run an individual case (greatest.h supports -t)


# Run a Ninja task.  The task file is "demanded" to run the examples/length.py file.
# TODO: the dependencies are a little weird here

rm _test/tasks/test/length.py.task.txt
ninja _test/tasks/test/length.py.task.txt

Related: