-
-
Notifications
You must be signed in to change notification settings - Fork 158
Contributing
NOTE: If anything on this page doesn't work for you, please file a bug!
(Related: Oil Native Quick Start / Where Contributors Have Problems / Oil Dev Cheat Sheet / Oil Dev Tips / Making Pull Requests)
One reason for this is that the spec tests run against four other shells (bash/dash/zsh/mksh), and we don't have a way of building the right versions of these shells on other OSes.
When I'm on a Mac, I use Ubuntu on Virtualbox to develop. Note that OSH does work on OS X for end users, but development is a different story.
Right now we have some awkwardness due to CI permissions.
We want you to send PRs from oilshell/oil
and not your own fork, so that Github Actions can get our $TOIL_KEY
, and publish HTML results to http://travis-ci.oilshell.org/ .
But this is a hiccup for first time contributors. I have to add you to the Github project so the CI can run. Ping me on Zulip!
This is the standard dev setup, which involves building tools like re2c
, Python 3, and MyPy.
Note that this process creates directories /wedge
and ~/wedge
. These are the only directories we touch outside the repository. To clean up the directories, you can simply run rm -rf /wedge ~/wedge
or build/deps.sh rm-oils-crap
. We plan to get rid of them, but we have not completed it yet.
This is for shells to test against, or custom Python-to-C++ translator, etc.
git clone https://github.com/oils-for-unix/oils.git # please use this repo, not your own fork
# this helps us use a Github Action secret on PRs
cd oils # enter the base directory
# Do ONE of these, depending on your distro
build/deps.sh wedge-deps-debian # Works on Ubuntu too -- uses sudo apt-get
# These are apt packages needed to build Python 2 and 3 from scratch ("wedges")
build/deps.sh wedge-deps-alpine # We test this in our sourcehut CI, so it should work!
build/deps.sh wedge-deps-fedora # Ditto, should work!
build/deps.sh fetch # Download a bunch of source tarballs
# If you're from China, maybe use:
# PY_FTP_MIRROR=https://mirrors.huaweicloud.com build/deps.sh fetch
build/deps.sh install-wedges-fast # Build and install in parallel - warning: writes to /wedge
build/py.sh all # Generates Python code - (re2c for lexer, CommonMark for help, etc.)
. build/dev-shell.sh # put our build of python2 in your $PATH
bin/osh -c 'echo hi' # Sanity check to make sure it works.
bin/ysh -c '= 1 + 2' # YSH sanity check
In case you get in trouble:
build/clean.sh # deletes all the temp files in the repo
build/deps.sh rm-oils-crap # deletes the build "wedges" outside the repo
# this is just rm -rf ~/wedge /wedge - latter requires root permissions
TODO: Clickable demo in gitpod or some other online dev env.
This can be a quicker way to get started. It only works if you already have python2
on your machine (python2
being deprecated, of course).
git clone https://github.com/oils-for-unix/oils.git
cd oils
build/py.sh wedge-deps-debian
build/py.sh minimal # MINIMAL dev build, including native/libc.c Python extension
. build/dev-shell.sh # Put build tools in $PATH
bin/osh -c 'echo hi'
This is all you need to make many changes to Oils.
test/unit.sh unit frontend/lexer_test.py # Run an individual unit test
test/unit.sh all # run most unit tests, takes about a second or two
test/spec.sh smoke # run a single file; there are more but this is a good start
test/spec-py.sh ysh-all # all YSH tests
See Spec Tests for details.
See Oil Dev Cheat Sheet for a summary of the commands above.
And tips on running more tests and benchmarks.
There are many other test suites which are reported on:
- The /release/$VERSION/quality.html page on every release
- The "Soil" continuous build at http://travis-ci.oilshell.org/github-jobs/
For example, you can run
test/parse-errors.sh all
To see a big demonstration of parse errors. I use this to supplement the spec tests when changing the syntax of the language.
If you did the above, then the Python bin/osh
should be working.
If you want to work on C++, then you should get _bin/cxx-asan/osh
to work. See Oil Native Quick Start, which links to the mycpp README.md
.
- Make sure to
build/dev.sh minimal
(orall
) after yougit pull
! The Python extension modules (.so
files) that OSH uses may be out of date, and they have to match the Python code. - Use
build/clean.sh
to start over.- It deletes all the temp files created by the tools, in underscore dirs like
_build
and_tmp
. - See Oil Dev Cheat Sheet
- It deletes all the temp files created by the tools, in underscore dirs like
-
Spec Tests are very important! Make sure you know how to run them quickly and maintain a fast, iterative development style.
-
Where Do I Put Spec Tests? If I'm going to change the behavior of the
source
builtin, I dogrep source spec/*.test.sh
and that leads to the spec test that should verify the new behavior.
-
Where Do I Put Spec Tests? If I'm going to change the behavior of the
-
Debugging Completion Scripts -- Use
--debug-file
!
Most people use Github pull requests to send patches. I will use Github's system to make comments. After addressing them, please:
- push the commits so I can see them
- reply with a message, like "All done", or "I disagree because ..."
If you only push commits, I won't look at the PR again, because I'll assume it's in progress.
Please feel free to ping andychu
on Zulip or Github if you're waiting for a pull request review! (or to ask questions)
Usually I can respond in 24 hours. I might be traveling, in which case I'll respond with something like I hope to look at this by Tuesday.
I might have also missed your Github message, so it doesn't hurt to ping me.
Thank you for the contributions!
Python code follows PEP 8, with some modifications from Google's Python style guide, like CapWords()
for function names.
- We use
yapf
to format Python code. See Oil Dev Cheat Sheet - We use
clang-format
for C++
- For shell code, also follow the existing style. It has 2 space indents,
funcs-like-this
(unless POSIX shell is required), andvars_like_this
. - C code generally follows the style that CPython uses (except 2 space indents?)
- See README.md
- https://www.oilshell.org/release/latest/pub/metrics.wwz/line-counts/overview.html
- https://www.oilshell.org/release/latest/pub/metrics.wwz/line-counts/for-translation.html
- Python App Bundle -- the old "OVM" build