| 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 |
|
| 77 | ### `sh` and Bash Docs Are Useful for OSH
|
| 78 |
|
| 79 | Existing educational materials for the Unix shell apply to OSH, because they
|
| 80 | generally don't teach the quirks that OSH disallows. For example, much of the
|
| 81 | information and advice in [BashGuide][] can be used without worrying about
|
| 82 | which shell you're using. See the end of this manual for more resources.
|
| 83 |
|
| 84 | For this reason, we're focusing efforts on documenting [YSH][].
|
| 85 |
|
| 86 | ## What Is Expected to Run Under OSH
|
| 87 |
|
| 88 | "Batch" programs are most likely to run unmodified under OSH. On the other
|
| 89 | hand, Interactive programs like `.bashrc` and bash completion scripts may
|
| 90 | require small changes.
|
| 91 |
|
| 92 | - Wiki: [What Is Expected to Run Under OSH]($wiki)
|
| 93 |
|
| 94 | ## Features Unique to OSH
|
| 95 |
|
| 96 | ### Dumping the AST
|
| 97 |
|
| 98 | The `-n` flag tells OSH to parse the program rather than executing it. By
|
| 99 | default, it prints an abbreviated abstract syntax tree:
|
| 100 |
|
| 101 | $ bin/osh -n -c 'ls | wc -l'
|
| 102 | (command.Pipeline children:[(C {(ls)}) (C {(wc)} {(-l)})] negated:F)
|
| 103 |
|
| 104 | You can also ask for the full `text` format:
|
| 105 |
|
| 106 | $ bin/osh -n --ast-format text -c 'ls | wc -l'
|
| 107 | (command.Pipeline
|
| 108 | children: [
|
| 109 | (command.Simple
|
| 110 | words: [
|
| 111 | (word.Compound
|
| 112 | parts: [(word_part.Literal
|
| 113 | token:(token id:Lit_Chars val:ls span_id:0))]
|
| 114 | )
|
| 115 | ]
|
| 116 | )
|
| 117 | (command.Simple
|
| 118 | words: [
|
| 119 | (word.Compound
|
| 120 | parts: [(word_part.Literal
|
| 121 | token:(token id:Lit_Chars val:wc span_id:4))]
|
| 122 | )
|
| 123 | (word.Compound
|
| 124 | parts: [(word_part.Literal
|
| 125 | token:(token id:Lit_Chars val:-l span_id:6))]
|
| 126 | )
|
| 127 | ]
|
| 128 | )
|
| 129 | ]
|
| 130 | negated: F
|
| 131 | spids: [2]
|
| 132 | )
|
| 133 |
|
| 134 | This format is **subject to change**. It's there for debugging the parser, but
|
| 135 | sophisticated users may use it to interpret tricky shell programs without
|
| 136 | running them.
|
| 137 |
|
| 138 |
|
| 139 | ### `OILS_HIJACK_SHEBANG`
|
| 140 |
|
| 141 | This environment variable can be set to the path of a **shell**. Before OSH
|
| 142 | executes a program, it will inspect the shebang line to see if it looks like a
|
| 143 | shell script. If it does, it will use this shell instead of the one specified
|
| 144 | in the shebang line.
|
| 145 |
|
| 146 | For example, suppose you have `myscript.sh`:
|
| 147 |
|
| 148 | #!/bin/sh
|
| 149 | # myscript.sh
|
| 150 |
|
| 151 | ./otherscript.sh --flag ...
|
| 152 |
|
| 153 | and `otherscript.sh`:
|
| 154 |
|
| 155 | #!/bin/sh
|
| 156 | # otherscript.sh
|
| 157 |
|
| 158 | echo 'hello world'
|
| 159 |
|
| 160 | Then you can run `myscript.sh` like this:
|
| 161 |
|
| 162 | OILS_HIJACK_SHEBANG=osh osh myscript.sh
|
| 163 |
|
| 164 | and `otherscript.sh` will be executed with OSH rather than the `/bin/sh`.
|
| 165 |
|
| 166 | Note that `osh` appears **twice** in that command line: once for the initial
|
| 167 | run, and once for all recursive runs.
|
| 168 |
|
| 169 | (This is an environment variable rather than a flag because it needs to be
|
| 170 | **inherited**.)
|
| 171 |
|
| 172 | ### `--debug-file`
|
| 173 |
|
| 174 | Print internal debug logs to this file. It's useful to make it a FIFO:
|
| 175 |
|
| 176 | mkfifo _tmp/debug
|
| 177 | osh --debug-file _tmp/debug
|
| 178 |
|
| 179 | Then run this in another window to see logs as you type:
|
| 180 |
|
| 181 | cat _tmp/debug
|
| 182 |
|
| 183 | Related:
|
| 184 |
|
| 185 | - The `OSH_DEBUG_DIR` environment variable is the inherited version of
|
| 186 | `--debug-file`. A file named `$PID-osh.log` will be written in that
|
| 187 | directory for every shell process.
|
| 188 | - The `--xtrace-to-debug-file` flag sends `set -o xtrace` output to that file
|
| 189 | instead of to `stderr`.
|
| 190 |
|
| 191 | ### Crash Dumps
|
| 192 |
|
| 193 | - TODO: `OSH_CRASH_DUMP_DIR`
|
| 194 |
|
| 195 | This is implemented, but a JSON library isn't in the release build.
|
| 196 |
|
| 197 | ### More
|
| 198 |
|
| 199 | For more features unique to Oils, see [Why Use Oils?][why]
|
| 200 |
|
| 201 | [why]: https://www.oilshell.org/why.html
|
| 202 |
|
| 203 |
|
| 204 | ## Appendix
|
| 205 |
|
| 206 | ### Bugs
|
| 207 |
|
| 208 | - OSH runs shell scripts too slowly. Speeding it up is a top priority.
|
| 209 |
|
| 210 | ### Links
|
| 211 |
|
| 212 | - [Blog Posts Tagged #FAQ][blog-faqs]
|
| 213 | tell you why OSH exists and how it's designed.
|
| 214 | - [Known Differences](known-differences.html) lists incompatibilities between
|
| 215 | OSH and other shells. They are unlikely to appear in real programs, or
|
| 216 | there is a trivial workaround.
|
| 217 |
|
| 218 | [blog-faqs]: https://www.oilshell.org/blog/tags.html?tag=FAQ#FAQ
|
| 219 |
|
| 220 | External:
|
| 221 |
|
| 222 | - [GNU Bash Manual](https://www.gnu.org/software/bash/manual/). I frequently
|
| 223 | referred to this document when implementing OSH.
|
| 224 | - [BashGuide][]. A wiki with detailed information about bash.
|
| 225 | - [BashPitfalls](https://mywiki.wooledge.org/BashPitfalls).
|
| 226 | - [Bash Cheat Sheet](https://devhints.io/bash). A short overview.
|
| 227 |
|
| 228 | [BashGuide]: https://mywiki.wooledge.org/BashGuide
|
| 229 |
|