| 1 | ---
|
| 2 | default_highlighter: oils-sh
|
| 3 | ---
|
| 4 |
|
| 5 | Getting Started
|
| 6 | ===============
|
| 7 |
|
| 8 | There are many ways to use Oils!
|
| 9 |
|
| 10 | - You can use it *interactively*, or you can write "shell scripts" with it.
|
| 11 | Shell is the best language for *ad hoc* automation.
|
| 12 | - You can use it in *compatible* mode with `bin/osh`, or in *legacy-free* mode
|
| 13 | with `bin/ysh`.
|
| 14 |
|
| 15 | As of 2024, [OSH][] is mature, and [YSH][YSH] is under development. See [blog
|
| 16 | posts tagged #FAQ][blog-faqs] for more detail.
|
| 17 |
|
| 18 | [OSH]: https://www.oilshell.org/cross-ref.html?tag=OSH#OSH
|
| 19 | [YSH]: https://www.oilshell.org/cross-ref.html?tag=YSH#YSH
|
| 20 |
|
| 21 | This doc walks you through setting up Oils, explains some concepts, and links
|
| 22 | to more documentation.
|
| 23 |
|
| 24 | <div id="toc">
|
| 25 | </div>
|
| 26 |
|
| 27 | ## Setup
|
| 28 |
|
| 29 | ### Downloading Oils
|
| 30 |
|
| 31 | The [releases page](https://www.oilshell.org/releases.html) links to source
|
| 32 | tarballs for every release. It also links to the documentation tree, which
|
| 33 | includes this page.
|
| 34 |
|
| 35 | ### Your Configuration Dir
|
| 36 |
|
| 37 | After running the instructions in [INSTALL](INSTALL.html), run:
|
| 38 |
|
| 39 | mkdir -p ~/.config/oils # for oshrc and yshrc
|
| 40 | mkdir -p ~/.local/share/oils # for osh_history
|
| 41 |
|
| 42 | ### Initialization with `rc` Files
|
| 43 |
|
| 44 | Note that
|
| 45 |
|
| 46 | - `bin/osh` runs `~/.config/oils/oshrc`
|
| 47 | - `bin/ysh` runs `~/.config/oils/yshrc`
|
| 48 |
|
| 49 | These are the **only** files that are "sourced". Other shells [have a
|
| 50 | confusing initialization sequence involving many files][mess] ([original][]).
|
| 51 | It's very hard to tell when and if `/etc/profile`, `~/.bashrc`,
|
| 52 | `~/.bash_profile`, etc. are executed.
|
| 53 |
|
| 54 | OSH and YSH intentionally avoid this. If you want those files, simply `source`
|
| 55 | them in your `oshrc`.
|
| 56 |
|
| 57 | [mess]: https://shreevatsa.wordpress.com/2008/03/30/zshbash-startup-files-loading-order-bashrc-zshrc-etc/
|
| 58 |
|
| 59 | [original]: http://www.solipsys.co.uk/new/BashInitialisationFiles.html
|
| 60 |
|
| 61 | I describe my own `oshrc` file on the Wiki: [How To Test
|
| 62 | OSH](https://github.com/oilshell/oil/wiki/How-To-Test-OSH).
|
| 63 |
|
| 64 | ## Tips
|
| 65 |
|
| 66 | - If you get tired of typing `~/.config/oils/oshrc`, symlink it to `~/.oshrc`.
|
| 67 |
|
| 68 | ### Troubleshooting
|
| 69 |
|
| 70 | - If you're running OSH from `bash` or `zsh`, then the prompt string `$PS1` may
|
| 71 | be unintentionally inherited. Running `PS1=''` before `bin/osh` avoids this.
|
| 72 | This is also true for `$PS2`, `$PS4`, etc.
|
| 73 | - On Arch Linux and other distros,`$LANG` may not get set without
|
| 74 | `/etc/profile`. Adding `source /etc/profile` to your `oshrc` may solve this
|
| 75 | problem.
|
| 76 | - See [OSH Compatibility Tips](https://github.com/oils-for-unix/oils/wiki/OSH-Compatibility-Tips) to configure programs that rely on `eval` to initialize (e.g. starship, zoxide).
|
| 77 |
|
| 78 | ### `sh` and Bash Docs Are Useful for OSH
|
| 79 |
|
| 80 | Existing educational materials for the Unix shell apply to OSH, because they
|
| 81 | generally don't teach the quirks that OSH disallows. For example, much of the
|
| 82 | information and advice in [BashGuide][] can be used without worrying about
|
| 83 | which shell you're using. See the end of this manual for more resources.
|
| 84 |
|
| 85 | For this reason, we're focusing efforts on documenting [YSH][].
|
| 86 |
|
| 87 | ## What Is Expected to Run Under OSH
|
| 88 |
|
| 89 | "Batch" programs are most likely to run unmodified under OSH. On the other
|
| 90 | hand, Interactive programs like `.bashrc` and bash completion scripts may
|
| 91 | require small changes.
|
| 92 |
|
| 93 | - Wiki: [What Is Expected to Run Under OSH]($wiki)
|
| 94 |
|
| 95 | ## Features Unique to OSH
|
| 96 |
|
| 97 | ### Dumping the AST
|
| 98 |
|
| 99 | The `-n` flag tells OSH to parse the program rather than executing it. By
|
| 100 | default, it prints an abbreviated abstract syntax tree:
|
| 101 |
|
| 102 | $ bin/osh -n -c 'ls | wc -l'
|
| 103 | (command.Pipeline children:[(C {(ls)}) (C {(wc)} {(-l)})] negated:F)
|
| 104 |
|
| 105 | You can also ask for the full `text` format:
|
| 106 |
|
| 107 | $ bin/osh -n --ast-format text -c 'ls | wc -l'
|
| 108 | (command.Pipeline
|
| 109 | children: [
|
| 110 | (command.Simple
|
| 111 | words: [
|
| 112 | (word.Compound
|
| 113 | parts: [(word_part.Literal
|
| 114 | token:(token id:Lit_Chars val:ls span_id:0))]
|
| 115 | )
|
| 116 | ]
|
| 117 | )
|
| 118 | (command.Simple
|
| 119 | words: [
|
| 120 | (word.Compound
|
| 121 | parts: [(word_part.Literal
|
| 122 | token:(token id:Lit_Chars val:wc span_id:4))]
|
| 123 | )
|
| 124 | (word.Compound
|
| 125 | parts: [(word_part.Literal
|
| 126 | token:(token id:Lit_Chars val:-l span_id:6))]
|
| 127 | )
|
| 128 | ]
|
| 129 | )
|
| 130 | ]
|
| 131 | negated: F
|
| 132 | spids: [2]
|
| 133 | )
|
| 134 |
|
| 135 | This format is **subject to change**. It's there for debugging the parser, but
|
| 136 | sophisticated users may use it to interpret tricky shell programs without
|
| 137 | running them.
|
| 138 |
|
| 139 |
|
| 140 | ### `OILS_HIJACK_SHEBANG`
|
| 141 |
|
| 142 | This environment variable can be set to the path of a **shell**. Before OSH
|
| 143 | executes a program, it will inspect the shebang line to see if it looks like a
|
| 144 | shell script. If it does, it will use this shell instead of the one specified
|
| 145 | in the shebang line.
|
| 146 |
|
| 147 | For example, suppose you have `myscript.sh`:
|
| 148 |
|
| 149 | #!/bin/sh
|
| 150 | # myscript.sh
|
| 151 |
|
| 152 | ./otherscript.sh --flag ...
|
| 153 |
|
| 154 | and `otherscript.sh`:
|
| 155 |
|
| 156 | #!/bin/sh
|
| 157 | # otherscript.sh
|
| 158 |
|
| 159 | echo 'hello world'
|
| 160 |
|
| 161 | Then you can run `myscript.sh` like this:
|
| 162 |
|
| 163 | OILS_HIJACK_SHEBANG=osh osh myscript.sh
|
| 164 |
|
| 165 | and `otherscript.sh` will be executed with OSH rather than the `/bin/sh`.
|
| 166 |
|
| 167 | Note that `osh` appears **twice** in that command line: once for the initial
|
| 168 | run, and once for all recursive runs.
|
| 169 |
|
| 170 | (This is an environment variable rather than a flag because it needs to be
|
| 171 | **inherited**.)
|
| 172 |
|
| 173 | ### `--debug-file`
|
| 174 |
|
| 175 | Print internal debug logs to this file. It's useful to make it a FIFO:
|
| 176 |
|
| 177 | mkfifo _tmp/debug
|
| 178 | osh --debug-file _tmp/debug
|
| 179 |
|
| 180 | Then run this in another window to see logs as you type:
|
| 181 |
|
| 182 | cat _tmp/debug
|
| 183 |
|
| 184 | Related:
|
| 185 |
|
| 186 | - The `OSH_DEBUG_DIR` environment variable is the inherited version of
|
| 187 | `--debug-file`. A file named `$PID-osh.log` will be written in that
|
| 188 | directory for every shell process.
|
| 189 | - The `--xtrace-to-debug-file` flag sends `set -o xtrace` output to that file
|
| 190 | instead of to `stderr`.
|
| 191 |
|
| 192 | ### Crash Dumps
|
| 193 |
|
| 194 | - TODO: `OSH_CRASH_DUMP_DIR`
|
| 195 |
|
| 196 | This is implemented, but a JSON library isn't in the release build.
|
| 197 |
|
| 198 | ### More
|
| 199 |
|
| 200 | For more features unique to Oils, see [Why Use Oils?][why]
|
| 201 |
|
| 202 | [why]: https://www.oilshell.org/why.html
|
| 203 |
|
| 204 |
|
| 205 | ## Appendix
|
| 206 |
|
| 207 | ### Bugs
|
| 208 |
|
| 209 | - OSH runs shell scripts too slowly. Speeding it up is a top priority.
|
| 210 |
|
| 211 | ### Links
|
| 212 |
|
| 213 | - [Blog Posts Tagged #FAQ][blog-faqs]
|
| 214 | tell you why OSH exists and how it's designed.
|
| 215 | - [Known Differences](known-differences.html) lists incompatibilities between
|
| 216 | OSH and other shells. They are unlikely to appear in real programs, or
|
| 217 | there is a trivial workaround.
|
| 218 |
|
| 219 | [blog-faqs]: https://www.oilshell.org/blog/tags.html?tag=FAQ#FAQ
|
| 220 |
|
| 221 | External:
|
| 222 |
|
| 223 | - [GNU Bash Manual](https://www.gnu.org/software/bash/manual/). I frequently
|
| 224 | referred to this document when implementing OSH.
|
| 225 | - [BashGuide][]. A wiki with detailed information about bash.
|
| 226 | - [BashPitfalls](https://mywiki.wooledge.org/BashPitfalls).
|
| 227 | - [Bash Cheat Sheet](https://devhints.io/bash). A short overview.
|
| 228 |
|
| 229 | [BashGuide]: https://mywiki.wooledge.org/BashGuide
|
| 230 |
|