diff --git a/build/doc.sh b/build/doc.sh index 592992212c..c5357c7fab 100755 --- a/build/doc.sh +++ b/build/doc.sh @@ -212,9 +212,9 @@ special() { render-only 'README.md' '../web/base.css ../web/manual.css ../web/toc.css' 'Oil Source Code' render-only 'INSTALL.txt' '../web/base.css ../web/install.css' 'Installing Oil' - # - + # These pages aren't in doc/ split-and-render doc/release-index.md _tmp/release-index.html + split-and-render doc/release-quality.md _tmp/release-quality.html } all-markdown() { diff --git a/devtools/release.sh b/devtools/release.sh index 65205a963f..b8c8ec394b 100755 --- a/devtools/release.sh +++ b/devtools/release.sh @@ -602,6 +602,16 @@ add-date-and-links() { ' } +modify-pages() { + local release_date + release_date=$(cat _build/release-date.txt) + + local root=_release/VERSION + + add-date-and-links $release_date < _tmp/release-index.html > $root/index.html + add-date-and-links $release_date < _tmp/release-quality.html > $root/quality.html +} + build-tree() { local root=_release/VERSION mkdir -p $root/{doc,test,pub} @@ -609,16 +619,11 @@ build-tree() { # Metadata cp -v _build/release-date.txt oil-version.txt $root - local release_date - release_date=$(cat _build/release-date.txt) - # Docs - # Writes _release/VERSION and _tmp/release-index.html build/doc.sh run-for-release - # Note: this truncates the date! - add-date-and-links $release_date < _tmp/release-index.html > $root/index.html + modify-pages # Problem: You can't preview it without .wwz! # Maybe have local redirects VERSION/test/wild/ to diff --git a/doc/release-index.md b/doc/release-index.md index 4228ce55ef..ab60bd3bbc 100644 --- a/doc/release-index.md +++ b/doc/release-index.md @@ -73,154 +73,7 @@ More docs: [Oil Deployments](https://github.com/oilshell/oil/wiki/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/spec.wwz/survey/osh.html). Test OSH with existing - shells, and compare their behavior. - - [Stateful Tests](test/spec.wwz/stateful/index.html). Tests that use - [pexpect]($xref). - - [OSH in C++](test/spec.wwz/cpp/osh-summary.html). The progress of Oil's - C++ translation. - - [Oil Language](test/spec.wwz/oil-language/oil.html). The legacy-free - language. -- [Wild Tests](test/wild.wwz/). Parse and translate thousands of shell scripts - with OSH. -- [Unit Tests](test/unit.wwz/). Python unit test results. - -### Other Suites - -- [Gold Tests](test/other.wwz/gold.txt). Compare OSH against bash (using - implicit assertions, no golden output.) -- [osh2oil Tests](test/other.wwz/osh2oil.txt). Test the conversion of OSH to - Oil. -- [parse-errors](test/other.wwz/parse-errors.txt). A list of all parse errors. - - [parse-errors-oil-native](test/other.wwz/parse-errors-oil-native.txt). - With the native binary. -- [runtime-errors](test/other.wwz/runtime-errors.txt). A list of shell runtime - errors. -- [oil-runtime-errors](test/other.wwz/oil-runtime-errors.txt). Oil language - runtime errors. -- [oil-large](test/other.wwz/oil-large.txt) -- [tea-large](test/other.wwz/tea-large.txt) -- [arena](test/other.wwz/arena.txt). Testing an invariant for the parser. -- [osh-usage](test/other.wwz/osh-usage.txt). Misc tests of the `osh` binary. -- [oshc-deps](test/other.wwz/oshc-deps.txt). Tests for a subcommand in - progress. -- [Smoosh][] test suite (from [mgree/smoosh][]): - - [smoosh](test/spec.wwz/survey/smoosh.html) - | [smoosh-hang](test/spec.wwz/survey/smoosh-hang.html) -- How many processes does Oil start compared to other shells? - - [syscall/by-code](test/other.wwz/syscall/by-code.txt) - | [syscall/by-input](test/other.wwz/syscall/by-input.txt) - -[Smoosh]: http://shell.cs.pomona.edu/ - -[mgree/smoosh]: https://github.com/mgree/smoosh/tree/master/tests/shell - -### Manual Tests - -- [ ] Test build and install on OS X - -## Benchmarks - -- [Parser](benchmarks.wwz/osh-parser/). How fast does OSH - parse compared to other shells? -- [Runtime](benchmarks.wwz/osh-runtime/). How fast does OSH run shell - scripts? -- [Compute](benchmarks.wwz/compute/). How fast does OSH run small programs - without I/O? -- [Build](benchmarks.wwz/ovm-build/). How long does it take for end users to - build Oil? How big is the resulting binary? -- [Virtual Memory Baseline](benchmarks.wwz/vm-baseline/). How much memory do - shells use at startup? -- [mycpp](benchmarks.wwz/mycpp-examples/). Compares Python and generated C++ - on small examples. - -## Metrics - -- Lines of source, counted in different ways: - - [overview](pub/metrics.wwz/line-counts/overview.html). The whole Oil repo organized by - type of source file. - - [for-translation](pub/metrics.wwz/line-counts/for-translation.html). - An overview of the "compile engineer" project. - - [osh-cloc](pub/metrics.wwz/line-counts/osh-cloc.txt). OSH and common - libraries, as measured by the [cloc][] tool. - - [oil-cpp](pub/metrics.wwz/line-counts/oil-cpp.txt). The C++ code in the - `oil-native` tarball. -- `oil-native`. - - [overview](pub/metrics.wwz/oil-native/overview.txt) - Binary code size reported - by [Bloaty][]. - - -[cloc]: https://github.com/AlDanial/cloc -[Bloaty]: https://github.com/google/bloaty -[OVM]: //www.oilshell.org/cross-ref.html?tag=OVM#OVM - -## 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](source-code.wwz/_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](source-code.wwz/frontend/lexer_def.py) - | [_devbuild/tmp/osh-lex.re2c.h](source-code.wwz/_devbuild/tmp/osh-lex.re2c.h) - | [_devbuild/gen/osh-lex.h](source-code.wwz/_devbuild/gen/osh-lex.h) -- [frontend/syntax.asdl](source-code.wwz/frontend/syntax.asdl). The syntax tree - for OSH and Oil. -- [oil_lang/grammar.pgen2](source-code.wwz/oil_lang/grammar.pgen2). The - expression grammar for Oil. In contrast, the OSH parsers are hand-written. - -Also see the [oilshell/oil](https://github.com/oilshell/oil) repository. - - - - - -## Old / Experimental - -These links describe the CPython / "[OVM]($xref)" 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/opy.wwz/build-oil-repo.txt) - | [test-gold](test/opy.wwz/test-gold.txt) - | [regtest-compile](test/opy.wwz/regtest-compile.txt) - | [regtest-verify-golden](test/opy.wwz/regtest-verify-golden.txt) -- Tree-shaking: [Symbols in Oil](test/opy.wwz/oil-symbols.txt) - | [Symbols in OPy](test/opy.wwz/opy-symbols.txt) -- [other/opyc](test/other.wwz/opyc.txt) - -### OPy / OVM Metrics - -- [OPy Line Counts](pub/metrics.wwz/line-counts/opy.txt). -- Lines of dependencies: - - [pydeps](pub/metrics.wwz/line-counts/pydeps.txt). Oil code plus the Python - standard library. - - [nativedeps](pub/metrics.wwz/line-counts/nativedeps.txt). Oil code plus a - slice of CPython. -- Bytecode Metrics - - [overview](pub/metrics.wwz/bytecode/overview.txt) - Compare OPy vs. CPython. - - [oil-with-opy](pub/metrics.wwz/bytecode/oil-with-opy.txt) - Oil compiled with - OPy. - - [oil-with-cpython](pub/metrics.wwz/bytecode/oil-with-cpython.txt) - Oil - compiled with CPython (for comparison). - - [src-bin-ratio-with-opy](pub/metrics.wwz/bytecode/src-bin-ratio-with-opy.txt) - - How big is the compiled output? -- OVM / CPython - - [overview](pub/metrics.wwz/ovm/overview.txt) - An analysis of GCC's - compilation of [OVM][] (a subset of CPython). [Bloaty][] provides the - underlying data. - - [cpython-defs/overview](pub/metrics.wwz/cpython-defs/overview.txt) - We try to - ship as little of CPython as possible, and this is what's left. +## Tests, Benchmarks, and Metrics + +The associated [quality page](quality.html) has many measurements. + diff --git a/doc/release-quality.md b/doc/release-quality.md new file mode 100644 index 0000000000..cab358d464 --- /dev/null +++ b/doc/release-quality.md @@ -0,0 +1,167 @@ +--- +css_files: web/base.css web/toc.css web/release-index.css +--- + +Oil 0.9.7 Quality +================= + + + + + + + +This is a supplement to the [release index](index.html). + +
+
+ +## Test Results + +### Spec Tests + +- [OSH Survey](test/spec.wwz/survey/osh.html). Test OSH with existing shells, + and compare their behavior. +- [Stateful Tests](test/spec.wwz/stateful/index.html). Tests that use + [pexpect]($xref). +- [OSH in C++](test/spec.wwz/cpp/osh-summary.html). The progress of Oil's C++ + translation. +- [Oil Language](test/spec.wwz/oil-language/oil.html). The legacy-free + language. + +### Other Primary Suites + +- [Gold Tests](test/other.wwz/gold.txt). Compare OSH against bash (using + implicit assertions, no golden output.) +- [Wild Tests](test/wild.wwz/). Parse and translate thousands of shell scripts + with OSH. +- [Unit Tests](test/unit.wwz/). Python unit test results. + +### More + +- [Smoosh][] test suite (from [mgree/smoosh][]): + - [smoosh](test/spec.wwz/survey/smoosh.html) + | [smoosh-hang](test/spec.wwz/survey/smoosh-hang.html) +- [parse-errors](test/other.wwz/parse-errors.txt). A list of all parse errors. + - [parse-errors-oil-native](test/other.wwz/parse-errors-oil-native.txt). + With the native binary. +- [runtime-errors](test/other.wwz/runtime-errors.txt). A list of shell runtime + errors. +- [oil-runtime-errors](test/other.wwz/oil-runtime-errors.txt). Oil language + runtime errors. +- [oil-large](test/other.wwz/oil-large.txt) +- [tea-large](test/other.wwz/tea-large.txt) +- [arena](test/other.wwz/arena.txt). Testing an invariant for the parser. +- [osh-usage](test/other.wwz/osh-usage.txt). Misc tests of the `osh` binary. +- [oshc-deps](test/other.wwz/oshc-deps.txt). Tests for a subcommand in + progress. +- How many processes does Oil start compared to other shells? + - [syscall/by-code](test/other.wwz/syscall/by-code.txt) + | [syscall/by-input](test/other.wwz/syscall/by-input.txt) +- [osh2oil Tests](test/other.wwz/osh2oil.txt). Test the conversion of OSH to + Oil. + +[Smoosh]: http://shell.cs.pomona.edu/ + +[mgree/smoosh]: https://github.com/mgree/smoosh/tree/master/tests/shell + +## Benchmarks + +- [Parser](benchmarks.wwz/osh-parser/). How fast does OSH + parse compared to other shells? +- [Runtime](benchmarks.wwz/osh-runtime/). How fast does OSH run shell + scripts? +- [Compute](benchmarks.wwz/compute/). How fast does OSH run small programs + without I/O? +- [Build](benchmarks.wwz/ovm-build/). How long does it take for end users to + build Oil? How big is the resulting binary? +- [Virtual Memory Baseline](benchmarks.wwz/vm-baseline/). How much memory do + shells use at startup? +- [mycpp](benchmarks.wwz/mycpp-examples/). Compares Python and generated C++ + on small examples. + +## Metrics + +- Lines of source, counted in different ways: + - [overview](pub/metrics.wwz/line-counts/overview.html). The whole Oil repo organized by + type of source file. + - [for-translation](pub/metrics.wwz/line-counts/for-translation.html). + An overview of the "compile engineer" project. + - [osh-cloc](pub/metrics.wwz/line-counts/osh-cloc.txt). OSH and common + libraries, as measured by the [cloc][] tool. + - [oil-cpp](pub/metrics.wwz/line-counts/oil-cpp.txt). The C++ code in the + `oil-native` tarball. +- `oil-native`. + - [overview](pub/metrics.wwz/oil-native/overview.txt) - Binary code size reported + by [Bloaty][]. + + +[cloc]: https://github.com/AlDanial/cloc +[Bloaty]: https://github.com/google/bloaty +[OVM]: //www.oilshell.org/cross-ref.html?tag=OVM#OVM + +## 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](source-code.wwz/_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](source-code.wwz/frontend/lexer_def.py) + | [_devbuild/tmp/osh-lex.re2c.h](source-code.wwz/_devbuild/tmp/osh-lex.re2c.h) + | [_devbuild/gen/osh-lex.h](source-code.wwz/_devbuild/gen/osh-lex.h) +- [frontend/syntax.asdl](source-code.wwz/frontend/syntax.asdl). The syntax tree + for OSH and Oil. +- [oil_lang/grammar.pgen2](source-code.wwz/oil_lang/grammar.pgen2). The + expression grammar for Oil. In contrast, the OSH parsers are hand-written. + +Also see the [oilshell/oil](https://github.com/oilshell/oil) repository. + + + + + +## Old + +These links describe the CPython / "[OVM]($xref)" 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/opy.wwz/build-oil-repo.txt) + | [test-gold](test/opy.wwz/test-gold.txt) + | [regtest-compile](test/opy.wwz/regtest-compile.txt) + | [regtest-verify-golden](test/opy.wwz/regtest-verify-golden.txt) +- Tree-shaking: [Symbols in Oil](test/opy.wwz/oil-symbols.txt) + | [Symbols in OPy](test/opy.wwz/opy-symbols.txt) +- [other/opyc](test/other.wwz/opyc.txt) + +#### OPy / OVM Metrics + +- [OPy Line Counts](pub/metrics.wwz/line-counts/opy.txt). +- Lines of dependencies: + - [pydeps](pub/metrics.wwz/line-counts/pydeps.txt). Oil code plus the Python + standard library. + - [nativedeps](pub/metrics.wwz/line-counts/nativedeps.txt). Oil code plus a + slice of CPython. +- Bytecode Metrics + - [overview](pub/metrics.wwz/bytecode/overview.txt) - Compare OPy vs. CPython. + - [oil-with-opy](pub/metrics.wwz/bytecode/oil-with-opy.txt) - Oil compiled with + OPy. + - [oil-with-cpython](pub/metrics.wwz/bytecode/oil-with-cpython.txt) - Oil + compiled with CPython (for comparison). + - [src-bin-ratio-with-opy](pub/metrics.wwz/bytecode/src-bin-ratio-with-opy.txt) - + How big is the compiled output? +- OVM / CPython + - [overview](pub/metrics.wwz/ovm/overview.txt) - An analysis of GCC's + compilation of [OVM][] (a subset of CPython). [Bloaty][] provides the + underlying data. + - [cpython-defs/overview](pub/metrics.wwz/cpython-defs/overview.txt) - We try to + ship as little of CPython as possible, and this is what's left.