README.md
1oksh
2====
3Portable OpenBSD `ksh(1)`. Not an official OpenBSD project.
4
5Why?
6----
7Because all operating systems deserve a good shell.
8
9Unlike other ports of OpenBSD ksh, this port is entirely self-contained and aims to be maximally portable across operating systems and C compilers.
10We are always looking for new combinations to add support for.
11
12Supported systems
13-----------------
14`oksh` is known to run on the following Operating Systems:
15* OpenBSD
16* FreeBSD
17* DragonFly BSD
18* NetBSD
19* HardenedBSD
20* SoloBSD (as the default shell)
21* Mac OS X (port originally by @geoff-nixon)
22* Linux (glibc and musl)
23* Cygwin
24* Android (via Termux)
25* AIX (with major thanks to @tssva and @NattyNarwhal)
26* IBM i PASE
27* Solaris
28* Illumos
29* midipix
30* WSL
31* WSL2
32* Unixware 7
33* Haiku
34* HP-UX (gcc only)
35* SerenityOS
36* MSYS2
37
38Running on a system not listed here? Add it and send a pull request!
39
40Believed working
41----------------
42We believe that `oksh` will work on the following platforms, but testing is needed.
43Help is greatly appreciated and encouraged!
44* Irix
45
46Supported compilers
47-------------------
48`oksh` is known to build with the following C compilers:
49* [clang](https://llvm.org/)
50* [gcc](https://gcc.gnu.org/)
51* [pcc](http://pcc.ludd.ltu.se/)
52* [cparser](https://pp.ipd.kit.edu/firm/)
53* [xlc](https://www.ibm.com/us-en/marketplace/ibm-c-and-c-plus-plus-compiler-family)
54* [Sun Studio compiler](https://www.oracle.com/technetwork/server-storage/developerstudio/overview/index.html)
55* [lacc](https://github.com/larmel/lacc)
56* Optimizing C Compilation System (CCS) 4.2 03/27/14 (uw714mp5.bl4s)
57* [Tiny C Compiler](https://bellard.org/tcc/)
58* [CompCert](https://compcert.org/)
59* [Nils Weller's C compiler](http://nwcc.sourceforge.net/)
60* [cproc](https://sr.ht/~mcf/cproc/) (Currently requires a small tweak to ignore a volatile store error)
61* [vbcc](http://www.compilers.de/vbcc.html) (Only tested on OpenBSD/i386)
62* [chibicc](https://github.com/rui314/chibicc)
63* [kefir](https://git.sr.ht/~jprotopopov/kefir)
64
65Building with a compiler not listed here? Add it and send a pull request!
66
67Packages
68--------
69`oksh` is included in some package systems.
70
71[](https://repology.org/project/oksh/versions)
72
73In addition, there are some unofficial packages:
74* [Ubuntu PPA](https://launchpad.net/~dysfunctionalprogramming/+archive/ubuntu/oksh)
75* [Debian](https://software.opensuse.org//download.html?project=home%3AHead_on_a_Stick%3Aoksh&package=oksh)
76
77Using a package not listed here? Add it and send a pull request!
78
79Dependencies
80------------
81A C99 compiler is the easiest way to ensure that `oksh` will build correctly.
82Please see the list of C compilers above for a list of known working compilers.
83
84Though not required, the `ncurses` library will be used for screen clearing
85routines if the library is found during the `configure` stage. This can be
86turned off by the user by passing the `--disable-curses` flag to `configure`.
87
88A `configure` script that produces a `POSIX` `Makefile` is provided to
89ease building and installation and can be run by:
90```
91$ ./configure
92$ make && sudo make install
93```
94
95Out-of-tree builds
96------------------
97The `configure` script will detect out-of-tree builds if you prefer to
98build out-of-tree. In order for this to work, the `VPATH` make extension
99is used. While not POSIX, `VPATH` is known to work with BSD make and GNU
100make. In-tree builds create a fully POSIX `Makefile`.
101
102Cross compiling
103---------------
104Cross compiling can be achieved by running `configure` as follows:
105```
106CC=/path/to/cross/cc CFLAGS="any needed cflags" LDFLAGS="any needed ldflags" ./configure --no-thanks
107```
108
109This will skip all `configure` checks and write out a generic `Makefile`
110and `pconfig.h` with nearly no options turned on. If using a cross gcc
111or clang, this very well may just work (with all compat compiled in).
112You can edit these files to reflect your system before running `make`.
113
114All environment variables and configure flags are respected when using
115`--no-thanks`. Further specifying `--no-link` after `--no-thanks` will
116only compile the source files into object files, to be transfered onto
117the target machine and linked there.
118
119The `--no-thanks` flag can also be used to compile a native `oksh` with
120all the compatibility functions compiled in, rather than relying on the
121system's version of those functions.
122
123Submitting patches
124------------------
125Patches that add new platforms and improve support for existing platforms
126are always welcome.
127
128Patches that cause `oksh` to deviate from upstream OpenBSD ksh behavior
129are better suited to be sent to the
130[OpenBSD tech@](https://www.openbsd.org/mail.html)
131mailing list. Please make sure to test your patch on an OpenBSD machine
132first before submitting it to tech@. I will sync with the upstream
133OpenBSD code once your patch is accepted. If you'd like to open an issue
134here to track progress of your patch on tech@, that's fine.
135
136License
137-------
138The main Korn shell files are public domain (see `LEGAL`).
139Portability files are BSD or ISC licensed; see individual file headers
140for details.
141
142Get a tarball
143-------------
144See releases tab. The latest release is oksh-7.5, which matches the ksh(1)
145from OpenBSD 7.5, released April 5, 2024.
