[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20130906025755.GE20515@brightrain.aerifal.cx>
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.
