From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/4016 Path: news.gmane.org!not-for-mail From: Rich Felker Newsgroups: gmane.linux.lib.musl.general Subject: Re: Second draft of musl documentation/manual Date: Thu, 5 Sep 2013 22:57:55 -0400 Message-ID: <20130906025755.GE20515@brightrain.aerifal.cx> References: <20130901044106.GA29630@brightrain.aerifal.cx> <20130906011252.GD20515@brightrain.aerifal.cx> <20130906024120.GP5116@port70.net> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1378436284 31592 80.91.229.3 (6 Sep 2013 02:58:04 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 6 Sep 2013 02:58:04 +0000 (UTC) To: musl@lists.openwall.com Original-X-From: musl-return-4020-gllmg-musl=m.gmane.org@lists.openwall.com Fri Sep 06 04:58:08 2013 Return-path: Envelope-to: gllmg-musl@plane.gmane.org Original-Received: from mother.openwall.net ([195.42.179.200]) by plane.gmane.org with smtp (Exim 4.69) (envelope-from ) id 1VHmFL-0000Fk-UH for gllmg-musl@plane.gmane.org; Fri, 06 Sep 2013 04:58:08 +0200 Original-Received: (qmail 23798 invoked by uid 550); 6 Sep 2013 02:58:07 -0000 Mailing-List: contact musl-help@lists.openwall.com; run by ezmlm Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: Original-Received: (qmail 23790 invoked from network); 6 Sep 2013 02:58:07 -0000 Content-Disposition: inline In-Reply-To: <20130906024120.GP5116@port70.net> User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:4016 Archived-At: On Fri, Sep 06, 2013 at 04:41:21AM +0200, Szabolcs Nagy wrote: > * Rich Felker [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