~amavect/mkphil

project structure philosophy for 9front
project structure philosophy

refs

front
browse  log 

clone

read-only
https://git.sr.ht/~amavect/mkphil
read/write
git@git.sr.ht:~amavect/mkphil

You can also use your local clone with git send-email.

Amavect-style Project Structure for 9front
Amavect
2021-06-09


ABSTRACT

Project repository and build structure is a matter of usability and taste.
The simpler the project, the less you need to worry about project structure.
When projects get large, some guidelines can help.
This philosophy guide is for 9front.


REPOSITORY

If your project is simple, less than 7 source files, keep it all as a flat directory.
Anything more than that and it's hard to read the output of `ls`.

A repository filesystem looks like this:

README
LICENSE
mkfile
src/
manpage1
manpage2
script1
script2

I like to see documents and the build scripts at the top level.
Users don't care about the source code as often as the build scripts,
so the source code goes into src/.

Installed scripts go in the top-level. Users can interact with these before installing.
If the scripts are installed in a /bin/subdir/ (like git/clone, git/diff),
then put them in a matching subfolder named such.

Man pages go in the top-level. This allows users to read them with nroff -man


BUILD

The mkfile should provide the following targets:
  all: Builds all executables and libraries. Always first, so it's the default target.
  install: Installs the executables and libraries to the right locations.
  clean: Removes all intermediate files.
  %.cpus: Calls mk $stem for all objtypes.

%.cpus:V:
	for(objtype in $CPUS) mk $stem

The user does not care about intermediate object files.
These clutter the src directory.
By making an obj directory, cleaning is easy: `rm -rf obj`.

obj:
	mk -p $target

obj/%.$O: obj src/%.c
	$CC $CFLAGS -o $target $prereq

Compiled executables must be placed on the top level, so the user can run them easily.


OPTIONAL

The mkfile can provide an uninstall target to remove all installed files.

The all target should populate an inst/ directory so the user may `walk -f inst` to see the staged files.
This allows the user to run `bind -b inst/$objtype/bin /$objtype/bin`