sc.conf.example

# sc.sh config, read once by "sh sc.sh" (no other invocation reads it).
# unknown keys are ignored, so this file can grow new keys without
# needing to change sc.sh itself. every key below is read only from
# this file -- there is no env var equivalent for any of them, unlike
# mp.conf's WD/PORTS_DIR/etc.
#
# sc.sh's whole job: probe this file's declared cflags/libs/headers/
# ldflags/funcs against the actual host, write the results to config.h,
# then generate mk.conf, a POSIX makefile, and mk/{b,c,d,dc}.sh (plus one
# mk/<name>.sh per custom target function defined below). re-run "sh
# sc.sh" any time this file changes -- nothing above regenerates itself.
 
# output binary name(s). at least one of bin= or libs= (below) is
# required -- sc.sh refuses to run with both unset. one name builds the
# common single-binary layout below; SEVERAL space-separated names
# build that many binaries from one project, e.g.:
#   bin="server client"
bin="myprogram"
 
# output library name(s), space-separated -- a project can set bin=,
# libs=, or both together freely (they don't interact: a bin= binary
# never automatically links against a libs= library, even one built by
# the same project -- give it an explicit source of its own, or its own
# hard_libs=/pkg-config entry, the same as any other dependency, if it
# genuinely needs to). each name builds THREE artifacts into "$out":
#   lib<name>.a              a plain static archive (ar rcs)
#   lib<name>.so.X.Y.Z       a real shared object, versioned, with
#                            lib<name>.so.X (soname symlink) and
#                            lib<name>.so (unversioned symlink) pointing
#                            at it -- the same convention every real
#                            shared library on the system already
#                            follows: linking "-l<name>" at runtime
#                            always resolves through the soname, so a
#                            minor/patch bump ships as a drop-in
#                            runtime replacement without recompiling
#                            anything that links against it.
#   lib<name>.pc             a pkg-config file (see PREFIX= below)
#
# resolved per-name exactly like bin= (a "$src/<name>/" subdirectory,
# or a "$src/<name>.c"/".s"/".S", or -- the fallback -- nothing of its
# own at all, drawing from the same $src/*.c shared pool bin= draws
# from), MINUS bin='s own three script kinds (.pl/.sh/bare) -- a
# "library" is inherently a compiled-C concept, there's no equivalent
# of installing a perl/sh script as one. unlike bin=, every object gets
# built TWICE, once plain (for the .a) and once as -fPIC (for the
# .so) -- the two can't share objects with each other, so this doubles
# the compile work for anything a libs= name actually owns (its own
# subdirectory/.c/.s/.S, or the shared pool once any libs= name draws
# from it) -- a project with only bin= names never pays this cost at
# all.
#libs=""
 
# ${name}_version="X.Y.Z" -- per-library version (one variable per
# libs= name, substituting the real name for "<name>"). controls both
# the .pc file's "Version:" field and the .so's own soname/filename
# (see libs= above) -- defaults to "0.0.0" if never set. only the major
# component (the part before the first ".") affects the soname itself;
# the rest is cosmetic (the .pc file, and the real filename), but
# still worth setting deliberately rather than leaving at the default.
#mylib_version="1.0.0"
 
# ${name}_desc="..." -- per-library one-line description, becomes the
# .pc file's "Description:" field. defaults to "<name> library" if
# never set.
#mylib_desc="a short description of mylib"
 
# PREFIX=, an environment variable (not a sc.conf key -- same
# convention as CC=/AR=/BTF2HTML=/BTF2MAN=, set when invoking sh sc.sh,
# not written here): the eventual install prefix, baked directly into
# every libs= name's own generated lib<name>.pc as its own "prefix="
# line (defaulting to "/usr/local" if never set). sc.sh itself never
# installs anything -- same as bin='s own compiled binaries, getting
# the .a/.so/.pc actually onto disk at $PREFIX/lib(/pkgconfig) is
# whatever wraps sc's own job (a port's install: phase, typically) --
# but the .pc file has to be generated with the CORRECT eventual prefix
# already baked in, since nothing rewrites it after the fact:
#   $ PREFIX=/usr sh sc.sh
 
# dir of sources to build. a .c/.s/.S directly under "$src" is SHARED:
# mk/b.sh compiles it once (via -MMD -MP, so header changes trigger the
# right recompiles) and links it into every COMPILED binary named in
# $bin. with a single bin= name and none of the per-name sources below,
# that's the whole story: every .c/.s/.S under "$src" is shared, and the
# one binary is built from all of it -- sc's original, most common
# shape, unchanged by anything below.
#
# a SECOND (or further) bin= name -- or a first one with a per-name
# source of its own -- resolves each name independently, checked in
# this order:
#   "$src/<name>/"       compiled: a whole subdirectory (several files,
#                         same shared/-per-file split as "$src" itself)
#   "$src/<name>.c"       compiled: one C file
#   "$src/<name>.s"/".S"  compiled: one assembly file (the same C
#                         compiler assembles .s/.S directly, no
#                         separate assembler needed)
#   "$src/<name>.pl"      a Perl script: syntax-checked ("perl -c") and
#                         installed as-is, no compiling or linking --
#                         the script itself is the artifact.
#   "$src/<name>.sh"      a POSIX sh script: same idea, checked with
#                         "sh -n" instead.
#   "$src/<name>"         a bare, extension-less file: a pre-built
#                         binary, or a script in some OTHER language sc
#                         doesn't know how to syntax-check -- installed
#                         exactly as-is, no validation attempted at all.
# a project can freely mix kinds across its own $bin names -- e.g.
# bin="server checkconfig.pl" builds server.c the normal compiled way
# and installs checkconfig.pl as a checked, ready-to-run script
# alongside it. a $cc is only ever required (and only then checked for
# at configure time) when at least one $bin name actually resolves to a
# compiled kind, or a hard_/soft_ cflags/libs/ldflags/funcs probe below
# is declared -- a project made entirely of perl/sh/generic names never
# needs a C compiler installed at all.
src="src"
 
# build output dir: object files, dep files, and the final "$out"/$bin.
# "mk . c" (mk/c.sh) removes only this directory -- config.h/mk.conf/
# makefile are configure-time output, re-run sc.sh to regenerate those,
# or remove them by hand.
#out="out"
 
# docs source dir: "$docsdir"/*.btft, rendered two ways, independently:
#   "mk . dh" (mk/dh.sh) -> "$docsdir"/html/, via btf2html (needs
#     "$docsdir"/style.btfs and btf2html itself on $PATH -- see
#     BTF2HTML= below to point at a non-$PATH copy).
#   "mk . dm" (mk/dm.sh) -> "$docsdir"/man/, via btf2man (no style.btfs
#     needed -- a man page has no concept of a stylesheet; see
#     BTF2MAN= the same way).
# "mk . d" (mk/d.sh) just runs both in one call. "mk . dc" (mk/dc.sh)
# removes BOTH rendered directories, never the *.btft sources. every
# *.btft page mirrors its own relative path under "$docsdir" into
# either output form.
#docsdir="docs"
 
# BTF2HTML=/BTF2MAN=, environment variables (not sc.conf keys -- set
# them when invoking make/mk, the same way CC= already overrides the
# compiler): point "mk . dh"/"mk . dm" at an exact btf2html/btf2man
# instead of whatever their own $PATH lookup would find, e.g. a build
# of either that isn't installed system-wide yet.
#   $ BTF2HTML=/path/to/btf2html make dh
 
# log dir: each of the six standard targets (b/c/dm/dh/d/dc) captures
# its own output to "$logdir"/<name>.log -- build.log, clean.log,
# docsman.log, docshtml.log, docsclean.log ("d" itself keeps none of
# its own: it's just two plain calls into dm.sh/dh.sh, each of which
# already writes its own). every log gets MORE than the terminal ever
# sees: a full "set -x" trace of every internal command the target's
# script ran (fd 2 stays pointed at the log for exactly this, restored
# to the terminal only for the few real external commands -- a
# compiler, btf2html/btf2man, rm -- so a genuine error from one of
# those still shows up live same as always), plus (for a build) the
# compiler's own "-v" identification dump, plus a final list of every
# file the target actually added or removed. real exit status is
# always intact either way, and terminal output never changes just
# because a log exists -- redirect a build to a file yourself and it's
# gone once the terminal scrolls away; this one persists. a custom
# target defined below gets no log of its own -- only the six standard
# ones are covered.
#logdir="logs"
 
# supported OSes, space-separated, matched against "uname -s | tr A-Z
# a-z" (so "Linux" -> "linux", "FreeBSD" -> "freebsd", etc). always a
# hard check with no soft equivalent -- an unsupported os aborts sc.sh
# immediately, before any of the probing below even starts. required,
# same as bin= above.
oss="linux freebsd netbsd openbsd"
 
# every hard_/soft_ category below (libs, headers, cflags, ldflags,
# funcs) takes a space-separated list, probed in that fixed order --
# cflags first (so the base compiler flags/macros apply to every probe
# after), then libs (folds each found lib's "pkg-config --cflags"/
# "--libs" into the accumulator), then headers (benefits from both),
# then ldflags, then funcs last (the most demanding probe: it gets the
# full accumulated cflags AND ldflags).
#
# hard_<category>: each item must be present/pass, or sc.sh aborts with
#   an error naming it.
# soft_<category>: checked the same way, but a failure just moves on --
#   config.h still gets a #define for it, valued 0 instead of 1.
#
# every checked item, hard or soft, gets a config.h macro either way, so
# C code can always write "#if LIB_FOO_C" regardless of which list it
# came from -- a hard item just never reaches config.h as a 0, since
# sc.sh would already have exited before writing it. the macro name is
# "<CATEGORY>_<NAME>_C" (e.g. hard_libs="zlib" -> LIB_ZLIB_C, hard_
# cflags="-Wall" -> CFLAG_WALL_C), with <NAME> uppercased and every
# character that isn't [A-Za-z0-9_] (a leading dash included) turned
# into an underscore -- so "sys/types.h" -> HEADER_SYS_TYPES_H_C and
# "libxml-2.0" -> LIB_LIBXML_2_0_C, both valid, collision-resistant C
# identifiers.
#
# a "_<os>" suffix on any of the ten (e.g. hard_libs_linux=, soft_
# funcs_netbsd=) adds to that category's plain list ONLY when that's the
# detected os -- use it for platform-specific deps (udev on linux,
# blocklist on netbsd, ...) instead of forking sc.conf per platform.
 
# libs: checked with "pkg-config --exists <name>". on success, that
# lib's "pkg-config --cflags"/"--libs" are folded into every later
# probe's flags and into the final build itself (mk.conf's ccflgs/
# ldflgs) -- a lib you never reference in hard_/soft_libs never affects
# the build at all, even if pkg-config could find it.
#hard_libs=""
#soft_libs=""
#hard_libs_linux=""
#soft_libs_netbsd=""
 
# headers: checked by preprocessing a bare "#include <name>" with cpp
# (plus whatever cflags/libs above already contributed).
#hard_headers=""
#soft_headers=""
 
# cflags: checked by compiling "int main(void) { return 0; }" with the
# flag and -Werror -- -Werror matters here specifically because some
# compilers (clang especially) silently accept any -f/-W flag they don't
# actually recognize unless told to error on it. a passing flag is
# folded into every later probe and the final build; example values:
#hard_cflags="-std=c99 -Wall -Wextra"
#soft_cflags=""
 
# ldflags: checked the same way as cflags, but linking instead of
# compiling (still with -Werror, same reasoning).
#hard_ldflags=""
#soft_ldflags=""
 
# funcs: checked by declaring the bare symbol (no header, no real
# prototype) and taking its address, then linking against the full
# accumulated cflags AND ldflags -- proves the symbol actually resolves
# against whatever libs got pulled in above, regardless of the symbol's
# real signature.
#hard_funcs=""
#soft_funcs=""
 
# custom targets: a plain shell function defined at column 0 (b/c/d/dc
# are reserved -- sc.sh refuses to generate over the standard build/
# clean/docs/docsclean targets) has its body lifted verbatim into
# mk/<name>.sh and wired into the generated makefile as target <name>,
# runnable as "make <name>" or "mk . <name>". example:
#
# h() {
# 	echo "usage: make [b|c|d|dc|h]"
# }