summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorWilliam Pitcock <nenolod@dereferenced.org>2017-06-14 18:56:49 +0000
committerWilliam Pitcock <nenolod@dereferenced.org>2017-06-14 18:56:49 +0000
commit57b03984a1f527616cfb62664228f873a3d84bef (patch)
tree4b6bb244a922812aefb4145500bb77b1ca646132 /README.md
parent918682c02bce090b0a8bd224883b38783ff0f8b0 (diff)
downloadgcompat-57b03984a1f527616cfb62664228f873a3d84bef.tar.gz
gcompat-57b03984a1f527616cfb62664228f873a3d84bef.tar.bz2
gcompat-57b03984a1f527616cfb62664228f873a3d84bef.tar.xz
gcompat-57b03984a1f527616cfb62664228f873a3d84bef.zip
add READMEgcompat-0.0.1
Diffstat (limited to 'README.md')
-rw-r--r--README.md49
1 files changed, 49 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4a5f188
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# 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}`. |
+
+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)
+
+Just 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.