docs: new file Documentation/howto-compilation.txt

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 64 insertions, 0 deletions

diff --git a/Documentation/howto-compilation.txt b/Documentation/howto-compilation.txt
new file mode 100644
index 000000000..3617b34c7
--- /dev/null
+++ b/Documentation/howto-compilation.txt
@@ -0,0 +1,64 @@
+The common case
+
+	./autogen.sh && ./configure && make
+
+	If something fails read the last lines. Typical reason to
+	fail is a missing dependency, such as libtool or gettext.
+
+Autotools
+
+	`./autogen.sh' generates all files needed to compile
+	and install the code (run it after checkout from git)
+
+	`make distclean' removes all unnecessary files, but the
+	code can still be recompiled with "./configure; make"
+
+	`make dist-gzip' (or -bzip2) creates a tarball that can
+	be configured and compiled without running `./autogen.sh'
+
+Compiling
+
+	Use SUID_CFLAGS and SUID_LDFLAGS when you want to define
+	special compiler options for typical suid programs, for
+	example:
+
+	./configure SUID_CFLAGS="-fpie" SUID_LDFLAGS="-pie"
+
+	The SUID_* feature is currently supported for chfn, chsh,
+	newgrp, write, mount, and umount.
+
+	Preferred compilation options for developers, when
+	using gcc, are:
+
+	export CFLAGS="-Wmissing-parameter-type -Wsign-compare
+	-Wtype-limits -Wuninitialized -Wunused-parameter
+	-Wunused-but-set-parameter -fno-common"
+
+	FIXME: add notes about klib and uClib.
+
+Static linking
+
+	Use --enable-static-programs[=LIST] configure option when
+	you want to use statically linked programs.
+
+	Note, mount(8) uses get{pw,gr}nam() and getpwuid()
+	functions for translation from username and groupname to
+	UID and GID. These functions could be implemented by
+	dynamically loaded independent modules (NSS) in your libc
+	(e.g. glibc). These modules are not statically linked to
+	mount(8) and mount.static is still using dlopen() like
+	dynamically linked version.
+
+	The translation won't work in environment where NSS
+	modules are not installed.
+
+	For example normal system (NSS modules are available):
+
+		# ./mount.static -v -f -n -ouid=kzak /mnt/foo
+		LABEL=/mnt/foo on /mnt/foo type vfat (rw,uid=500)
+							 ^^^^^^^
+	and without NSS modules:
+
+		# chroot . ./mount.static -v -f -n -ouid=kzak /mnt/win
+		LABEL=/mnt/win on /mnt/win type vfat (rw,uid=kzak)
+							 ^^^^^^^^