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

143 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)](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
35[git-repo]: https://github.com/oils-for-unix/oils
36
37<div id="toc">
38</div>
39
40## Contributing
41
42* Try making the **dev build** of Oils with the instructions on the
43 [Contributing][] page. This should take 1 to 5 minutes if you have a Linux
44 machine.
45* If it doesn't, let us know. You can post on the `#oil-dev` channel of
46 [oilshell.zulipchat.com][], or file an issue on Github.
47* Feel free to grab an [issue from
48 Github](https://github.com/oils-for-unix/oils/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
49 Let us know what you're thinking before you get too far.
50
51[Contributing]: https://github.com/oils-for-unix/oils/wiki/Contributing
52[oilshell.zulipchat.com]: https://oilshell.zulipchat.com/
53[blog]: https://www.oilshell.org/blog/
54
55### Quick Start on Linux
56
57After following the instructions on the [Contributing][] page, you'll have a
58Python program that you can quickly run and change! Try it interactively:
59
60 bash$ bin/osh
61
62 osh$ name=world
63 osh$ echo "hello $name"
64 hello world
65
66- Try running a shell script you wrote with `bin/osh myscript.sh`.
67- Try [YSH][] with `bin/ysh`.
68
69Let us know if any of these things don't work! [The continuous
70build](https://op.oilshell.org/) tests them at every commit.
71
72### Dev Build vs. Release Build
73
74Again, note that the **developer build** is **very different** from the release
75tarball. The [Contributing][] page describes this difference in detail.
76
77The release tarballs are linked from the [home page][home-page]. (Developer
78builds don't work on OS X, so use the release tarballs on OS X.)
79
80### Important: We Accept Small Contributions!
81
82Oils is full of [many ideas](https://oils.pub/blog/), which may be
83intimidating at first.
84
85But the bar to contribution is very low. It's basically a medium size Python
86program with many tests, and many programmers know how to change such programs.
87It's great for prototyping.
88
89- For OSH compatibility, I often merge **failing [spec
90 tests](https://oils.pub/cross-ref.html#spec-test)**. You don't even
91 have to write code! The tests alone help. I search for related tests with
92 `grep xtrace spec/*.test.sh`, where `xtrace` is a shell feature.
93- You only have to make your code work **in Python**. Plain Python programs
94 are easy to modify. The semi-automated translation to C++ is a separate
95 step, although it often just works.
96- You can **influence the design** of [YSH][]. If you have an itch to
97 scratch, be ambitious. For example, you might want to show us how to
98 implement [nonlinear pipelines](https://github.com/oils-for-unix/oils/issues/843).
99
100### I aim for 24 hour response time
101
102Please feel free to ping `andychu` on Zulip or Github if you're **waiting** for
103a pull request review! (or to ask questions)
104
105Usually I can respond in 24 hours. I might be traveling, in which case I'll
106respond with something like *I hope to look at this by Tuesday*.
107
108I might have also **missed** your Github message, so it doesn't hurt to ping
109me.
110
111Thank you for the contributions!
112
113### Docs
114
115The [Wiki](https://github.com/oils-for-unix/oils/wiki) has many developer docs. Feel
116free to edit them. If you make a major change, let us know on Zulip!
117
118If you're confused, the best thing to do is to ask on Zulip and someone should
119produce a pointer and/or improve the docs.
120
121Docs for **end users** are linked from each [release
122page](https://oils.pub/releases.html).
123
124## Repository Structure
125
126See the [Oils Repo Overview][repo-overview], and
127[README-index.md](README-index.md).
128
129[repo-overview]: doc/repo-overview.md
130
131## More info
132
133There are README files in many subdirectories, like
134[mycpp/README.md](mycpp/README.md).
135
136* [The blog][blog] has updates on the project status.
137* [Oils Home Page][home-page]
138* [oilshell.zulipchat.com][] is for any kind of discussion
139* Subscribe for updates:
140 * [/r/oilshell on Reddit](https://www.reddit.com/r/oilshell/)
141 * [@oilsforunix on Twitter](https://twitter.com/oilsforunix)
142
143