-
-
Notifications
You must be signed in to change notification settings - Fork 164
Oil Dev Cheat Sheet
Yihang Liu edited this page Apr 9, 2024
·
82 revisions
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).
This is a series of commands walking you through a develop build.
- Building
build/deps.sh fetch build/deps.sh install-wedges-fast # If you're from China use the below command instead # PY_FTP_MIRROR=https://mirrors.huaweicloud.com build/deps.sh install-wedges-fast build/py.sh all build/dev-shell.sh # works for bash
- Running
bin/ysh # for ysh bin/osh # for osh
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
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
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.)
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
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.
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/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: