Documentation
¶
Overview ¶
Build builds code as directed by json files. We slurp in the JSON, and recursively process includes. At the end, we issue a single cc command for all the files. Compilers are fast.
ENVIRONMENT ¶
Needed: CC, HARVEY, ARCH
HARVEY should point to a harvey root. A best-effort to autodetect the harvey root is made if not explicitly set.
Optional: AR, LD, RANLIB, STRIP, SH, TOOLPREFIX
These all control how the needed tools are found.
BUILDFILE FORMAT ¶
A buildfile is a json object containing build objects. By convention, it's broken out onto multiple lines indented by tabs, and the keys are TitleCased.
The environment varibles HARVEY and ARCH are guarenteed to be set for the buildfile. PATH is modified so that "$HARVEY/util" is included.
Any key that takes a path or array of paths as its value has absolute paths re-rooted to the harvey tree and variables in the string expanded once.
The shell commands in the "Pre" and "Post" steps must be in the subset of syntax that's accepted by both POSIX sh and rc. Practically, this means arguments with a "=" must be single-quoted, "test" must be called as "test" (not "["), "if" statements may not have an "else" clause, "switch" statements may not be used, "for" statements may only have one body command, and redirection to a file descriptor cannont be used.
BUILD OBJECT ¶
A build object has the following keys and types:
Projects []string Pre []string Post []string Cflags []string Oflags []string Include []string SourceFiles []string ObjectFiles []string Libs []string Env []string SourceFilesCmd []string Program string Library string Install string Kernel kernel
These are the steps taken, in order:
Env Include Projects Pre Kernel [compile] SourceFiles SourceFilesCmd Cflags Program [link] ObjectFiles Libs Oflags Library Install Post
"[compile]" and "[link]" are steps synthesized from the specified keys.
The meaning of the keys is as follows:
"Env" is an array of environment variables to be put in the environment of every command run in a build. They are expanded once and only available for use in other steps.
"Include" is an array of buildfiles to "merge" into the current one. This is done before other projects are built.
"Projects" is an array of buildfiles to build in their entirety before starting the current build.
"Pre" is an array of commands to run before starting the build.
"Kernel" is a kernel build object. See the kernel object section.
"Cflags" is an array of flags to pass to the C compiler. They are in addition to the standard flags of
-std=c11 -c -I /$ARCH/include -I /sys/include -I .
The standard include paths are re-rooted to the harvey tree if not on a harvey system.
"SourceFilesCmd" is an array of C files where each one should result in an executable. If this key is provided, "SourceFiles" and "Program" are ignored.
"SourceFiles" is an array of C files that will ultimately produce a single binary or library, named by "Program" or "Library" respectively.
"Program" is the name of the final executable for the files specified by "SourceFiles".
"Oflags" is an array of flags to pass to the linker. They are in addition to the standard flags of
-o $program $objfiles -L /$ARCH/lib $libs
The lib path is re-rooted to the harvey tree if not on a harvey system.
"ObjectFiles" is an array of strings specifying object files to be linked into the final program specified by "Program". Any object files produced by the preceeding "[compile]" step are automatically added to this before beginning the "[link]" step.
"Libs" is a an array of library arguments to pass to the linker.
"Library" is the name of the archive resulting from bundling "SourceFiles" into a library. The resulting archive has 'ranlib' run on it automatically.
"Install" is a directory where the result of the "[link]" step is moved to. If it does not exist, it is created.
"Post" is an array of commands to run last during the build.
KERNEL OBJECT ¶
A build object has the following keys and types:
Systab string Ramfiles map[string]string Config { Code []string Dev []string Ip []string Link []string Sd []string Uart []string VGA []string }
"Systab" is the header that defines the syscall table.
"Ramfiles" is an object of name, path pairs of binaries at "path" that will be baked into the kernel and available at a binary named "name".
"Config" is an object used to generate the kernel configuration source. "Dev", "Ip", "Sd", "Uart", "Link", and "VGA" control which drivers of the various types are included. "Code" is lines of arbitrary C code.