add READMEgcompat-0.0.1

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.