shithub: docs.9front.org

Download patch

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.