From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/4015 Path: news.gmane.org!not-for-mail From: Szabolcs Nagy Newsgroups: gmane.linux.lib.musl.general Subject: Re: Second draft of musl documentation/manual Date: Fri, 6 Sep 2013 04:41:21 +0200 Message-ID: <20130906024120.GP5116@port70.net> References: <20130901044106.GA29630@brightrain.aerifal.cx> <20130906011252.GD20515@brightrain.aerifal.cx> 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 1378435289 22781 80.91.229.3 (6 Sep 2013 02:41:29 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 6 Sep 2013 02:41:29 +0000 (UTC) To: musl@lists.openwall.com Original-X-From: musl-return-4019-gllmg-musl=m.gmane.org@lists.openwall.com Fri Sep 06 04:41:33 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 1VHlzJ-0002sq-P5 for gllmg-musl@plane.gmane.org; Fri, 06 Sep 2013 04:41:33 +0200 Original-Received: (qmail 16095 invoked by uid 550); 6 Sep 2013 02:41:32 -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 16087 invoked from network); 6 Sep 2013 02:41:32 -0000 Content-Disposition: inline In-Reply-To: <20130906011252.GD20515@brightrain.aerifal.cx> User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:4015 Archived-At: * 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,...) > #### 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 > #### 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) > #### 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 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 LD_PRELOAD and environment variable dependencies should be documented around here as well and the security policy for setuid binaries > 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