INSTALL

Generic instructions
~~~~~~~~~~~~~~~~~~~~
Build sequence is similar to generic autotools packages:

	./configure (...)
	make
	make DESTDIR=(...) install

Run "./configure help" to see possible options.

Alternatively, check config.mk and/or config.h.
Specifically, check INITCTL, INITTAB, LOGDIR in config.h,
compiler setup and installation directories in config.mk.


PIE issues / relocation errors / stack protector errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some distributions configure gcc with PIE and/or SSP enabled
by default. Depending on gcc version, PIE may break -static
builds with errors like this:

  /usr/bin/ld: libc.a(sigaction.o): relocation R_X86_64_32S against `.text'
          can not be used when making a shared object; recompile with -fPIC
  /usr/bin/ld: final link failed: Nonrepresentable section on output

In properly configured toolchains -static alone should fix this, but some
toolchains also need -fno-pie.

SSP may be enabled by default as well, resulting in error messages like this:

  init.o: In function `setpasstime':
  init.c:(.text+0x5e): undefined reference to `__stack_chk_fail'

SSP must be disabled as it will probably not work with the bundled libc
(and dietlibc, and possibly anything that's not system libc).


Cross-compiling
~~~~~~~~~~~~~~~
Set CC and AR in config.mk for your target architecture.
Alternatively, run configure --target=(toolchain-prefix).

sninit follows Linux kernel naming scheme, with CC for target executables
and HOSTCC for build system executables.


Packaging for small size
~~~~~~~~~~~~~~~~~~~~~~~~
Simple make install does not strip executables.
If you need stripped executable, run this instead:

	make DESTDIR=(...) install-stripped

If you don't need man pages as well, use

	make DESTDIR=(...) install-bin-stripped


Building with bundled libc
~~~~~~~~~~~~~~~~~~~~~~~~~~
sninit comes with a stripped-down, minimalistic subset of dietlibc
capable just enough to fit sninit demands.
Sample usage (cross-build for mips):

	ARCH = mips
	CC = mipsel-linux-gnu-gcc -march=mips2

CC will be called with -nostdinc -nostdlib so it does not matter
which libc, if any, it has in its sysroot.

Check libc/ subdirectories to see which architectures are supported
by bundled libc. For unsupported architectures, fall back to dietlibc
or perhaps system libc.

Using bundled libc may be more convenient, but provides little benefit
over *properly*configured* dietlibc in terms of executable size
(because it is mostly dietlibc, if perhaps re-written in some places).
Instead gives clear, uncluttered libc code for debugging.

Note properly configured dietlibc. Depending on target architecture,
default dietlibc configuration may add several kB of bloat.
See doc/dietlibc.txt


Building with dietlibc
~~~~~~~~~~~~~~~~~~~~~~
Recommended settings:
	CC = diet gcc
or
	CC = diet clang
Use "configure diet gcc" or "configure diet clang" respectively.

Dietlibc up to and including 0.33 does not provide ppoll(2) system call.
Either use sys_ppoll.c (indirect syscall, via syscall(2)), or patch dietlibc.

Because dietlibc implies static linkage and small executable size,
consider using sys_printf.c and sys_strerror.c. See comments in those files.
Size optimization (-Os) helps in most cases.


Building with musl
~~~~~~~~~~~~~~~~~~
Use CC = musl-gcc when building on non-musl system.

If musl-gcc complains about linux/*.h, you probably have no linux headers
in musl-gcc path. Symlink /usr/include/linux and /usr/include/asm to
$MUSL/include/linux and $MUSL/include/asm respectively.

For musl-based systems, no settings should be necessary.

Configure options: "musl-gcc" for non-native builds, "musl" for musl toolchains.


Building with glibc or uClibc
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Both glibc and uclibc lack getdents(2), even thought it is a linux system call.
Use sys_getdents.c instead.


Link-time optimization
~~~~~~~~~~~~~~~~~~~~~~
To enable LTO, add -flto to CFLAGS and LDFLAGS, or alternatively use "lto"
keyword for configure. It should work with any libc.

LTO is generally harmless, but it requires support from cc/binutils, and its
effects are usually minor. Because of this, it is not enabled by default.

LTO does not work out-of-the-box with clang at this moment.


Rebuilding
~~~~~~~~~~
Run "make clean" before rebuilding with a different ARCH value
or with a different libc type. Those affect config.mk, and Makefile
does not track dependencies on config.mk

Use "make distclean" to remove all generated files including target executable.
Note however that config.h and config.mk are modified in place, there are no
autoconf-style config.h.in or config.mk.in, so distclean will not restore them.