ref: 60b95550c1069b88c2334c53c995e16811c61dc1
parent: 959c6f1f51c1ef6b72a28262885102d4ce9e1255
author: Sigrid Solveig Haflínudóttir <ftrvxmtrx@gmail.com>
date: Wed Mar 3 06:14:38 EST 2021
add an initial post on how to port alien software without ape
--- a/howto.md
+++ b/howto.md
@@ -18,3 +18,5 @@
[Youtube](youtube.html)
[VMX](vmx.html)
+
+[Porting alien software *without* APE](porting.html)
--- /dev/null
+++ b/porting.md
@@ -1,0 +1,49 @@
+# Porting alien software *without* APE
+
+To get started on an easy port of a POSIX library (or a program), one
+can use
+[helpmeport](https://git.sr.ht/~ft/snippets/blob/master/helpmeport)
+script. It tries to generate the appopriate headers and a `mkfile`.
+
+ cd coollib
+ # sometimes, the source files are located in `src` subdir
+ # if it's in the current directory, just specify `.` instead
+ rm -rf mkfile src/plan9 # remove old stuff
+ helpmeport src | rc
+ # now there is `src/plan9` directory and `mkfile`
+ # `mkfile` needs manual adjustments: open it and search for "FIXME"
+ # make your choices (name of the library/program, etc)
+ # clean up headers and sources, some of them might be platform-specific
+ B mkfile
+ # now try to build. there is 99% it won't work the first time
+ mk
+
+Depending on the result of the build, some changes of the source code
+might be required.
+
+The script will provide `__plan9__` and eg `__amd64__` definitions to
+be used throughout, in case needed.
+
+Feel free to show your script patches and ideas to Sigrid.
+
+## Common issues
+
+### function not declared: ...
+
+If the function defined in the project, and has no arguments, make
+sure it's declared as `(void)` instead of `()`.
+
+### alloca
+
+`alloca` allocates memory on stack, so that freeing it isn't required.
+Plan 9 does not have that. It has to be replaced with `malloc` and
+`free` call before leaving the function.
+
+### *_MAX or *_MIN not declared
+
+Grep `/sys/include` to see if it's already defined in APE:
+
+ g UCHAR_MAX /sys/include/ape
+
+In most of the cases you can just add it to `src/plan9/plan9.h`. Be
+careful if the size depends on the CPU you're targetting.