From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.org/gmane.linux.lib.musl.general/3993 Path: news.gmane.org!not-for-mail From: Rich Felker Newsgroups: gmane.linux.lib.musl.general Subject: Initial draft of musl documentation/manual Date: Sun, 1 Sep 2013 00:41:06 -0400 Message-ID: <20130901044106.GA29630@brightrain.aerifal.cx> Reply-To: musl@lists.openwall.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="cNdxnHkX5QqsyA0e" X-Trace: ger.gmane.org 1378010476 32292 80.91.229.3 (1 Sep 2013 04:41:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 1 Sep 2013 04:41:16 +0000 (UTC) To: musl@lists.openwall.com Original-X-From: musl-return-3997-gllmg-musl=m.gmane.org@lists.openwall.com Sun Sep 01 06:41:21 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 1VFzTU-0000Go-8O for gllmg-musl@plane.gmane.org; Sun, 01 Sep 2013 06:41:20 +0200 Original-Received: (qmail 10002 invoked by uid 550); 1 Sep 2013 04:41:19 -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 9988 invoked from network); 1 Sep 2013 04:41:18 -0000 Content-Disposition: inline User-Agent: Mutt/1.5.21 (2010-09-15) Xref: news.gmane.org gmane.linux.lib.musl.general:3993 Archived-At: --cNdxnHkX5QqsyA0e Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Hi all, The big agenda item for the next release is drafting the official documentation for musl. While this task still has a long way to go, and much of it is still a skeleton, there's also a decent amount of actual content, and it's helping me come up with ideas for other content that should be included. Comments on the draft are welcome, especially on the matter of additional topics that readers might expect to find which I have overlooked.. For reference, it's based on the outline in the "New docs outline" thread on the mailing list, from 2012-11-15. One more thing: the format of the document is presently Markdown (http://daringfireball.net/projects/markdown/). I may switch to something else in the future, but Markdown tends to be my favorite from a standpoint of being fully readable as plain text and also producing decent formatted output in HTML (and other formats, via conversion from HTML). Comments on this bikeshed topic are also welcome, I suppose, unless it gets out of hand... Rich --cNdxnHkX5QqsyA0e Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="manual4.txt" musl ==== Part I - About musl ------------------- ### Introduction and Scope musl is an implementation of the userspace portion of the standard library functionality described in the ISO C and POSIX standards, plus common extensions. It is both a component for use in Linux-based operating systems and a tool for building application binaries deployable on a wide range of Linux-based systems and non-Linux systems which can provide a compatible syscall API layer. ### Conformance statements The interfaces in musl are modeled upon and intended to conform to the requirements of the ISO C99 standard (ISO/IEC 9899-1999), including Annex F, and POSIX 2008 / Single Unix Standard Version 4, with all current technical corrigenda applied. However, musl has not been certified by any standards body, and no guarantee of conformance is made by the copyright holders or any other party with an interest in musl. Moreover, since musl provides only the userspace portion of the standard system interfaces, conformance to the requirements of POSIX depends in part on the behavior of the underlying kernel. Linux 2.6.39 or later is believed to be sufficient; earlier versions in the 2.6 series will work, but with varying degrees of non-conformance, particularly in the area of signal handling behavior and close-on-exec race conditions. Likewise, conformance to the requirements of ISO C, and especially Annex F (IEEE floating point semantics), depends in part on both the compiler used to build musl and the compiler used when building applications against musl. At this time there is no known fully conforming compiler. ### Supported Systems To be written. ### Build and Installation To be written. ### Installed Components #### 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. #### 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. The file `libc.a` installed in `$(libdir)` provides the entire standard library implementation for static linking. The file `libc.so` provides the linker with access to the standard library's symbols for use at link-time in producing dynamic-linked binaries. It is not searched at runtime; the standard library is resolved as part of the program interpreter at `$(syslibdir)/ld-musl-$(ARCH).so.1`. Additional files `libm.a`, `librt.a`, `libpthread.a`, `libcrypt.a`, `libutil.a`, `libxnet.a`, `libresolv.a`, and `libdl.a` are provided in `$(libdir)` as empty library archives. They contain no code, but are present to satisfy the POSIX requirement that options of the form `-lm`, `-lpthread`, etc. be accepted by the `c99` compiler. Several bare object files are also included in `$(libdir)`: `crt1.o` and `Scrt1.o` are the normal and position-independent versions, respectively, of the entry point code linked into every program. `crti.o` and `crtn.o`, also linked into every program and into shared libraries, provide support for legacy means by which the compiler can arrange for global constructors and destructors to be executed. It is possible to setup a legacy-free compiler toolchain that does not need the `crti.o` and `crtn.o` files if desired. #### 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 * `/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. * `/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. 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. --cNdxnHkX5QqsyA0e--