From 50484015cfc355fba5acff5effb83a10820ec099 Mon Sep 17 00:00:00 2001 From: "A. Wilcox" Date: Sun, 28 Apr 2019 23:12:27 -0500 Subject: Finally use an Adélie style README here MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 69 ------------------ README.rst | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+), 69 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 7fb3ef7..0000000 --- a/README.md +++ /dev/null @@ -1,69 +0,0 @@ -# gcompat - -The gcompat project provides a glibc-compatible runtime environment for distributions that use musl libc. - -It provides a compatibility library as well as a loader which injects the compatibility library. The loader -is installed where the glibc ELF interpreter (`/lib/ld-linux.so.2`) would normally be, allowing for execution -of glibc programs to work in the same way as native musl programs. - - -## building gcompat - -In order to build correctly, the gcompat build system requires a few details about the host environment, both -from the musl end, as well as the glibc end. These are: - -| Variable | Description | -|--------------------|---------------------------------------------------------------------------------------------------| -| `LINKER_PATH` | The location of the musl ELF interpreter. | -| `LOADER_NAME` | The name of the glibc ELF interpreter that would be appropriate for your architecture. | -| `LIBGCOMPAT_PATH` | *optional* The location to install the libgcompat.so library to. Usually `/lib/libgcompat.so.0`. | -| `LOADER_PATH` | *optional* The location to install the loader to. Usually `/lib/${LOADER_NAME}`. | -| `WITH_LIBUCONTEXT` | *optional* Whether or not to build against `libucontext`. | - -For example on x86_64 musl with x86_64 glibc compatibility, you would want to do: - -``` -$ make LINKER_PATH=/lib/ld-musl-x86_64.so.1 LOADER_NAME=ld-linux-x86-64.so.2 -$ make LINKER_PATH=/lib/ld-musl-x86_64.so.1 LOADER_NAME=ld-linux-x86-64.so.2 install -``` - -The `DESTDIR` environment variable is available for the convenience of packagers. - - -## running programs under gcompat - -Assuming everything is in the right place, the programs should just work. If they are not working, check the program's -ELF interpreter entry, using scanelf(8) like so: - -``` -$ scanelf -i ~/glibcfile - TYPE INTERP FILE -ET_EXEC /lib64/ld-linux-x86-64.so.2 /home/kaniini/glibcfile -``` - -If the interpreter path is different than expected, use PatchELF or install a symlink to the interpreter. - - -## making musl programs accept glibc binaries for dlopen(3) - -You have two options: - -* You can add libgcompat.so to the DT_NEEDED entries in the ELF that you want to have the gcompat symbols available in. - Use a tool such as PatchELF for this. - -* Alternatively, you can link the musl binary against libgcompat. - - -## special environment variables - -* `GLIBC_FAKE_VERSION` will override the result of `gnu_get_libc_version`, which currently defaults to "2.8". -* `GLIBC_FAKE_DEBUG` will cause dlmopen and dlvsym to display the overrides they are performing, and may cause - additional output to stderr with other functions in the future. - -## reporting issues - -If you are having issues with gcompat, please report them at our [bug tracker](https://bts.adelielinux.org/). - -## contributing - -If you want to contribute code or documentation, please see the CONTRIBUTING.rst file in this repository. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..a419f26 --- /dev/null +++ b/README.rst @@ -0,0 +1,232 @@ +==================== + README for gcompat +==================== +:Authors: + * **A. Wilcox**, initial concept, maintainer, lead developer + * **Adélie Linux and its contributors**, development +:Status: + Production +:Copyright: + © 2019 Adélie Linux and contributors. MIT open source license. + + +.. image:: https://img.shields.io/badge/chat-on%20IRC-blue.svg + :target: ircs://irc.interlinked.me:6697/#Adelie-Support + +.. image:: https://img.shields.io/codacy/grade/1e94efed5989436fa416ede784d4f7b6.svg + :target: https://app.codacy.com/project/awilfox/gcompat/dashboard + +.. image:: https://img.shields.io/badge/license-NCSA-lightgrey.svg + :target: LICENSE + +.. image:: https://repology.org/badge/vertical-allrepos/gcompat.svg + :target: https://repology.org/project/gcompat/versions + + +Introduction +============ + +This distribution contains the implementation of **gcompat**, a library which +provides glibc-compatible APIs for use on musl libc systems. + +This library is designed to be used for binaries that are already compiled +against glibc. It does not contain any headers, and cannot be used to build +software that requires glibc. It is instead recommended that any software that +requires glibc APIs be modified to become more portable. + +This library can optionally be compiled with other libraries to make a single, +unfied solution. This can include fts_, libucontext_, obstack_, and others. + +*gcompat* additionally provides a loader stub. This is a small library that +has the same name as the glibc dynamic linker on glibc platforms; when a binary +is run that uses glibc as its dynamic linker, the stub will run, redirecting it +to use musl and automatically preloading the gcompat library. + + +.. _fts: https://github.com/pullmoll/musl-fts/ +.. _libucontext: https://code.foxkit.us/adelie/libucontext/ +.. _obstack: https://github.com/pullmoll/musl-obstack/ + + +License +``````` +This library is provided under the NCSA open source license. + + +Changes +``````` +Any changes to this repository must be reviewed before being pushed to the +master branch. There are no exceptions to this rule. For security-sensitive +updates, contact the Security Team at sec-bugs@adelielinux.org. + + + +Background +========== + +Many applications distributed for Linux are built against glibc. +Unfortunately, many of glibc's internals are leaked out in to the resultant +binary which makes it difficult or impossible to run these binaries on systems +using the `musl libc`_. + +While the goal of Adélie Linux is to support only true Libre Software that can +be built from source code, we recognise that some users may require the ability +to run pre-compiled binaries on their computers. This may include older +software that does not compile with modern compilers, or non-libre software +such as firmware or device management software. + +.. _`musl libc`: http://www.musl-libc.org/ + + + +Supported Environments +====================== +The following architectures are supported: + +* x86 (32-bit) + + This is a Tier 1 architecture in the Adélie Linux system, as *pmmx*. + +* x86_64 + + This is a Tier 1 architecture in the Adélie Linux system. + +* armv6+ (as ``arm``) + + This is a Tier 2 architecture in the Adélie Linux system, as *armv6* and + *armv7*. As such, it may not receive thorough testing. + +* aarch64 + + This is a Tier 1 architecture in the Adélie Linux system. + +* s390x + + This architecture is **not supported** by the Adélie Linux system. It is + *untested* by the release team and may not be functional. + +The following architectures utilise a Linux kernel syscall: + +* ppc (32-bit) + + This is a Tier 1 architecture in the Adélie Linux system. + +* ppc64 + + This is a Tier 1 architecture in the Adélie Linux system. Only the ELFv2 ABI + is supported, and only Big Endian modes of operation are tested by the + release team. + + + +Building +======== + +In order to build correctly, the gcompat build system requires a few details +about the host environment, regarding both the musl host and glibc target. To +provide this information to the build system, you will need to set the +following variables or pass them to ``make``. + +* ``LINKER_PATH`` + + The location of the musl ELF interpreter. On PowerPC, this is + ``/lib/ld-musl-powerpc64.so.1``. + +* ``LOADER_NAME`` + + The location of the glibc ELF interpreter. On PowerPC, this is + ``ld.so.2``. + +You may additionally specify any of the following optional variables for +further customisation: + +* ``DESTDIR`` + + The directory in which to install files. The default value is ``/``. + +* ``LIBGCOMPAT_PATH`` + + The location in which to install ``libgcompat.so``, relative to ``DESTDIR``. + The default value is ``/lib/libgcompat.so.0``. + +* ``LOADER_PATH`` + + The location in which to install the glibc interpreter stub. The default + value is ``/lib/$LOADER_NAME``. + +* ``WITH_LIBUCONTEXT`` + + Determines whether to build with libucontext_. + +For example, on an x86_64 musl host and x86_64 glibc target, you may run: + + $ make LINKER_PATH=/lib/ld-musl-x86_64.so.1 LOADER_NAME=ld-linux-x86-64.so.2 + + $ make LINKER_PATH=/lib/ld-musl-x86_64.so.1 LOADER_NAME=ld-linux-x86-64.so.2 install + +Please note that unlike libucontext, the gcompat build system does *not* +attempt to guess the correct values for you. This feature may be added later. + + + +Usage +===== + +Running binaries linked against glibc +------------------------------------- + +If the values specified during build were correct, programs built for glibc +should run normally on your musl host. If they are not working, check the +program's ELF interpreter entry, using scanelf(8) like so: + +`` +$ scanelf -i ~/glibcfile + TYPE INTERP FILE +ET_EXEC /lib64/ld-linux-x86-64.so.2 /home/kaniini/glibcfile +`` + +If the interpreter path is different than expected, use PatchELF or install a +symlink from ``LOADER_PATH`` to the specified interpreter. + + +Using glibc binaries via dlopen(3) from a musl program +------------------------------------------------------ + +There are two ways to accomplish this: + +* You can add libgcompat.so to the DT_NEEDED entries in the ELF that you want + to have the gcompat symbols available in. Use a tool such as PatchELF for + this. + +* Alternatively, you can link the musl binary against libgcompat. + +Environment variables +--------------------- + +* ``GLIBC_FAKE_VERSION`` + + The value of ``GLIBC_FAKE_VERSION`` will be returned as the result of + ``gnu_get_libc_version``. The current default is "2.8". + +* ``GLIBC_FAKE_DEBUG`` + + Setting this variable will cause dlmopen and dlvsym to display the overrides + they are performing, and may cause additional output to stderr with other + functions in the future. + + + + +Reporting Issues +================ + +gcompat is released by the Adélie Linux project in the hopes that it is useful +to the community. Current issues may be found at our BTS_; you may also +`submit an issue`_ there. + +For general discussion, questions, or to submit a patch, please use the +`gcompat mailing list`_. + +.. _BTS: https://bts.adelielinux.org/buglist.cgi?product=gcompat&resolution=--- +.. _`submit an issue`: https://bts.adelielinux.org/enter_bug.cgi?product=gcompat +.. _`gcompat mailing list`: https://lists.adelielinux.org/postorius/lists/gcompat.lists.adelielinux.org/ -- cgit v1.2.3-70-g09d2