OILS / README.md View on Github | oils.pub

140 lines, 97 significant
1Oils Source Code
2================
3
4[![Build
5Status](https://github.com/oils-for-unix/oils/actions/workflows/all-builds.yml/badge.svg?branch=master)](https://github.com/oils-for-unix/oils/actions/workflows/all-builds.yml) <a href="https://gitpod.io/from-referrer/">
6 <img src="https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod" alt="Contribute with Gitpod" />
7</a>
8
9[Oils][home-page] is our upgrade path from bash to a better language and runtime!
10
11- [OSH][] runs your existing shell scripts.
12- [YSH][] is for Python and JavaScript users who avoid shell.
13
14(The project was [slightly renamed][rename] in March 2023, so there are still
15old references to "Oil". Feel free to send pull requests with corrections!)
16
17[home-page]: https://oils.pub/
18
19[OSH]: https://oils.pub/cross-ref.html#OSH
20[YSH]: https://oils.pub/cross-ref.html#YSH
21
22[rename]: https://www.oilshell.org/blog/2023/03/rename.html
23
24[Oils 2023 FAQ][faq-2023] / [Why Create a New Unix Shell?][why]
25
26[faq-2023]: https://www.oilshell.org/blog/2023/03/faq.html
27[why]: https://www.oilshell.org/blog/2021/01/why-a-new-shell.html
28
29It's written in Python, so the code is short and easy to change. But we
30automatically translate it to C++ with custom tools, to make it fast and small.
31The deployed executable doesn't depend on Python.
32
33This README is at the root of the [git repo][git-repo].
34
35If you want to **use** Oils, don't clone this repo. Instead, visit
36<https://oils.pub/release/latest/>.
37[The Oils Repo Is Different From theTarball Releases](https://github.com/oils-for-unix/oils/wiki/The-Oils-Repo-Is-Different-From-the-Tarball-Releases).
38
39[git-repo]: https://github.com/oils-for-unix/oils
40
41<div id="toc">
42</div>
43
44## Contributing
45
46* Try making the **dev build** of Oils with the instructions on the
47 [Contributing][] page. This should take 1 to 5 minutes if you have a Linux
48 machine.
49* If it doesn't, let us know. You can post on the `#oil-dev` channel of
50 [oilshell.zulipchat.com][], or file an issue on Github.
51* Feel free to grab an [issue from
52 Github](https://github.com/oils-for-unix/oils/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
53 Let us know what you're thinking before you get too far.
54
55[Contributing]: https://github.com/oils-for-unix/oils/wiki/Contributing
56[oilshell.zulipchat.com]: https://oilshell.zulipchat.com/
57[blog]: https://oils.pub/blog/
58
59### Quick Start on Linux
60
61After following the instructions on the [Contributing][] page, you'll have a
62Python program that you can quickly run and change! Try it interactively:
63
64 bash$ bin/osh
65
66 osh$ name=world
67 osh$ echo "hello $name"
68 hello world
69
70- Try running a shell script you wrote with `bin/osh myscript.sh`.
71- Try [YSH][] with `bin/ysh`.
72
73Let us know if any of these things don't work! [The continuous
74build](https://op.oilshell.org/) tests them at every commit.
75
76### Dev Build vs. Release Build
77
78Again, note that the **developer build** is **very different** from the release
79tarball. The [Contributing][] page describes this difference in detail.
80
81The release tarballs are linked from the [home page][home-page]. (Developer
82builds don't work on OS X, so use the release tarballs on OS X.)
83
84### Important: We Accept Small Contributions!
85
86Oils is full of [many ideas](https://oils.pub/blog/), which may be
87intimidating at first.
88
89But the bar to contribution is very low. It's basically a medium size Python
90program with many tests, and many programmers know how to change such programs.
91It's great for prototyping.
92
93- For OSH compatibility, I often merge **failing [spec
94 tests](https://oils.pub/cross-ref.html#spec-test)**. You don't even
95 have to write code! The tests alone help. I search for related tests with
96 `grep xtrace spec/*.test.sh`, where `xtrace` is a shell feature.
97- You only have to make your code work **in Python**. Plain Python programs
98 are easy to modify. The semi-automated translation to C++ is a separate
99 step, although it often just works.
100- You can **influence the design** of [YSH][]. If you have an itch to
101 scratch, be ambitious. For example, you might want to show us how to
102 implement [nonlinear pipelines](https://github.com/oils-for-unix/oils/issues/843).
103
104### I aim for 24 hour response time
105
106Please feel free to ping `andychu` on Zulip or Github if you're **waiting** for
107a pull request review! (or to ask questions)
108
109Usually I can respond in 24 hours. I might be traveling, in which case I'll
110respond with something like *I hope to look at this by Tuesday*.
111
112I might have also **missed** your Github message, so it doesn't hurt to ping
113me.
114
115Thank you for the contributions!
116
117## Docs
118
119The [Wiki](https://github.com/oils-for-unix/oils/wiki) has many developer docs. Feel
120free to edit them. If you make a major change, let us know on Zulip!
121
122If you're confused, the best thing to do is to ask on Zulip and someone should
123produce a pointer and/or improve the docs.
124
125Docs for **end users** are linked from each [release
126page](https://oils.pub/releases.html).
127
128## Links
129
130* The [Oils Home Page][home-page] has all the important links.
131* Related:
132 * Repository Structure: See the [Oils Repo Overview][repo-overview]
133 * The [README-index.md](README-index.md) links to docs for some
134 subdirectories. For example, [mycpp/README.md](mycpp/README.md) is pretty
135 detailed.
136 * FAQ: [The Oils Repo Is Different From the Tarball][repo-tarball-faq]
137
138[repo-overview]: doc/repo-overview.md
139
140[repo-tarball-faq]: https://github.com/oils-for-unix/oils/wiki/The-Oils-Repo-Is-Different-From-the-Tarball-Releases