source | all versions | oilshell.org

Oil 0.9.4

This is the home page for version 0.9.4 of Oil, a Unix shell. To use it,

1. Download a source tarball.
2. Build it and do a "smoke test", as described in INSTALL.

These steps take 30 to 60 seconds on most machines. After installation, see Getting Started.

Test results, metrics, and benchmarks are shown below.

Download

Note: oil-native is a preview release, not a working shell.

What's New

• Details are in the raw git change log. Not all changes affect the release tarball.
• I sometimes write a release announcement with a high-level description of changes.

Documentation

The Doc Overview links to all docs. Here is the subset of them that are ready to read:

• Getting Started
• OSH:
  • Known Differences Between OSH and Other Shells | Quirks | Tracing Execution | Headless Mode
• The Oil language:
  • A Tour of the Oil Language | Oil vs. Shell Idioms and Shell Idioms | Shell Language Deprecations | Oil Language FAQ | Egg Expressions (Oil Regexes) | Simple Word Evaluation | Variable Declaration, Mutation, and Scope | Warts
• Language Design:
  • A Feel For Oil's Syntax | Syntactic Concepts | Command vs. Expression Mode | Language Influences
• Interchange Formats:
  • QSN

More docs:

• OSH Help Topics (in progress) | Oil Help Topics (in progress).
• Github Wiki for oilshell/oil. The Oil Deployments wiki page has other ways of getting Oil. These versions may not be up-to-date.

Tests

Main Test Suites

• Spec Tests
  • OSH Survey. Test OSH with existing shells, and compare their behavior.
  • OSH in C++. The progress of Oil's C++ translation.
  • Oil Language. The legacy-free language.
• Wild Tests. Parse and translate thousands of shell scripts with OSH.
• Unit Tests. Python unit test results.

Other Suites

• Gold Tests. Compare OSH against bash (using implicit assertions, no golden output.)
• osh2oil Tests. Test the conversion of OSH to Oil.
• parse-errors. A list of all parse errors.
  • parse-errors-oil-native. With the native binary.
• runtime-errors. A list of shell runtime errors.
• oil-runtime-errors. Oil language runtime errors.
• oil-large
• tea-large
• arena. Testing an invariant for the parser.
• osh-usage. Misc tests of the osh binary.
• oshc-deps. Tests for a subcommand in progress.
• Smoosh test suite (from mgree/smoosh):
  • smoosh | smoosh-hang
• How many processes does Oil start compared to other shells?
  • syscall/by-code | syscall/by-input

Manual Tests

• [ ] Test build and install on OS X

Benchmarks

• Parser. How fast does OSH parse compared to other shells?
• Runtime. How fast does OSH run shell scripts?
• Compute. How fast does OSH run small programs without I/O?
• Build. How long does it take for end users to build Oil? How big is the resulting binary?
• Virtual Memory Baseline. How much memory do shells use at startup?
• mycpp. Compares Python and generated C++ on small examples.

Metrics

• Lines of source, counted in different ways:
  • osh-cloc. OSH and common libraries, as measured by the cloc tool.
  • src. The whole Oil repo organized by type of source file.
  • oil-cpp. The C++ code in the oil-native tarball.
• oil-native.
  • overview - Binary code size reported by Bloaty.

Source Code

These files may help you understand how Oil is implemented, i.e. with domain-specific languages and code generation.

• _devbuild/gen/id.h. A list of language elements, used in the lexer and in multiple parsers and evaluators.
• The regex-based lexer uses two stages of code generation:
  • frontend/lexer_def.py | _devbuild/tmp/osh-lex.re2c.h | _devbuild/gen/osh-lex.h
• frontend/syntax.asdl. The syntax tree for OSH and Oil.
• oil_lang/grammar.pgen2. The expression grammar for Oil. In contrast, the OSH parsers are hand-written.

Also see the oilshell/oil repository.

Old / Experimental

These links describe the CPython / "OVM" build, which should become the "experimental" version of Oil.

OPy Tests

The OPy compiler is used to compile Oil to bytecode, but isn't itself part of the release.

• build-oil-repo | test-gold | regtest-compile | regtest-verify-golden
• Tree-shaking: Symbols in Oil | Symbols in OPy
• other/opyc

OPy / OVM Metrics

• OPy Line Counts.
• Lines of dependencies:
  • pydeps. Oil code plus the Python standard library.
  • nativedeps. Oil code plus a slice of CPython.
• Bytecode Metrics
  • overview - Compare OPy vs. CPython.
  • oil-with-opy - Oil compiled with OPy.
  • oil-with-cpython - Oil compiled with CPython (for comparison).
  • src-bin-ratio-with-opy - How big is the compiled output?
• OVM / CPython
  • overview - An analysis of GCC's compilation of OVM (a subset of CPython). Bloaty provides the underlying data.
  • cpython-defs/overview - We try to ship as little of CPython as possible, and this is what's left.