Date: Thu, 5 Sep 2013 22:57:55 -0400 From: Rich Felker <dalias@...ifal.cx> To: musl@...ts.openwall.com Subject: Re: Second draft of musl documentation/manual On Fri, Sep 06, 2013 at 04:41:21AM +0200, Szabolcs Nagy wrote: > * Rich Felker <dalias@...ifal.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
Powered by blists - more mailing lists
Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.