Re: Second draft of musl documentation/manual

[Rich Felker <dalias@aerifal.cx>]

On Fri, Sep 06, 2013 at 04:41:21AM +0200, Szabolcs Nagy wrote:
> * Rich Felker <dalias@aerifal.cx> [2013-09-05 21:12:52 -0400]:
> > #### Prerequisites
> > 
> > The only build-time prerequisites for musl are the standard POSIX
> > shell and utilities, GNU Make (version 3.81 or later) and a
> > freestanding C99 compiler toolchain targeting the desired instruction
> > set architecture and ABI, with support for gcc-style inline assembly,
> > weak aliases, and stand-alone assembly source files.
> > 
> 
> there are some optional extensions and compiler defined macros
> or builtins which may worth listing somewhere
> (noreturn, noalias, typeof, 1.0i,...)

Is 1.0i needed for compiling musl? I thought CMPLX() would be used,
but I haven't checked. The others are not needed for compiling musl
(used optionally, dependent on __GNUC__), but may be needed for
compiling applications using certain headers. I'm documenting this in
Part II. So far tgmath.h and complex.h are the only examples I have
where a header _needs_ an extension to work. Do you know others I
should document?

> > #### Dynamic linking runtime
> > 
> > `$(syslibdir)/ld-musl-$(ARCH).so.1` provides the dynamic linker, or
> > "program interpreter", for dynamically linked ELF programs using musl.
> > The absolute pathname to this file must be stored in all such
> > programs. The build and installation system provided with musl sets it
> > up as a symbolic link to `$(libdir)/libc.so`, but system integrators
> > may choose to make it available in whichever ways they find suitable.
> > 
> 
> in the usage section:
> ../libc.so pathname args
> ../ldd pathname

Good idea.

> > #### Development environment
> > 
> > Header files for use by the C compiler are installed in
> > `$(includedir)`. The standard headers are fully self-contained, and do
> > not make use of kernel-provided or compiler-provided headers or
> > otherwise require such headers to be present.
> 
> it is also worth noting that header files are not c99 (they are
> intended to be c89 except for long long and possibly wchar_t literals
> and should be usable with c++ as well)

Yes, I've already written that text in Part II (in progress right
now).

> > #### Compiler wrapper
> > 
> > To be written.
> > 
> > 
> > ### Filesystem Layout Dependencies
> > 
> > musl aims to avoid imposing filesystem policy; however, the following
> > minimal set of filesystems dependencies must be met in order for
> > programs using musl to function correctly:
> > 
> > * `/dev/null` - required by POSIX
> > 
> > * `/dev/tty` - required by POSIX
> > 
> > * `/tmp` - required by POSIX to exist as a directory, and used by
> > various temporary file creation functions.
> > 
> > * `/dev/shm` - must be a directory, and should have permissions 01777.
> > If absent, POSIX shared memory and named semaphore interfaces will
> > fail; programs not using these features will be unaffected.
> > 
> > * `/dev/ptmx` - must exist and be accessible for read/write in order
> > for pseudo-terminal opening to work.
> > 
> > * `/dev/pts` - must be a mounted devpts filesystem in order for
> > pseudo-terminal opening to work.
> > 
> > * `/proc` - must be a mount point for Linux procfs or a symlink to
> > such. Several functions such as realpath, fexecve, and a number of the
> > "at" functions added in POSIX 2008 need access to /proc to function
> > correctly.
> > 
> > * `/etc/resolv.conf` - needed to provide addresses of nameservers to
> > be used for DNS lookups, unless a working nameserver is available on
> > the loopback address.
> > 
> > * `../etc/ld-musl-$(ARCH).path`, taken relative to the location of the
> > "program interpreter" specified in the program's headers - if present,
> > this will be processed as a text file containing the shared library
> > search path, with components delimited by newlines or colons. If
> > absent, a default path of `"/lib:/usr/local/lib:/usr/lib"` will be
> > used. Not used by static-linked programs.
> > 
> 
> i'd probably repeat the program interpreter here again

OK.

> and i'd list all paths that may be used
> 
> /bin/sh
> 
> /etc/shadow or /etc/tcb/...
> /etc/passwd
> /etc/group
> 
> default zoneinfo search paths
> 
> /dev/log
> 
> /etc/services
> /etc/hosts

Indeed. Thanks for finding these.

> LD_PRELOAD and environment variable dependencies should be documented
> around here as well

Perhaps these (and the above filesystem dependencies) should be in
Part II. Also, we might want to add separate parts for run-time and
development usage.

> and the security policy for setuid binaries

Good idea.

> > Part II - Usage
> > ---------------
> > 
> > To be written. This part of the manual will deal with documenting
> > implementation-defined behavior and further behaviors that are not
> > required to be documented but for which musl makes additional
> > guarantees.
> > 
> > 
> > 
> > Part III - Implementation
> > -------------------------
> > 
> > To be written. This part of the manual will document the
> > implementation of musl, including matters such as source tree layout,
> > built system, algorithms used, musl-internal APIs, coding style, and
> > information on porting.
> 
> the documentation looks good so far

Thanks!

Rich