Fork of the Android NDK crazy linker.

third_party/android_crazy_linker/src/README.TXT

Index: third_party/android_crazy_linker/src/README.TXT
diff --git a/third_party/android_crazy_linker/src/README.TXT b/third_party/android_crazy_linker/src/README.TXT
new file mode 100644
index 0000000000000000000000000000000000000000..bf0540215ace6a243e4d7ba375c29cace93bd3a7
--- /dev/null
+++ b/third_party/android_crazy_linker/src/README.TXT
@@ -0,0 +1,137 @@
+Introduction:
+-------------
+
+A custom dynamic linker for Android programs that adds a few interesting
+features compared to /system/bin/linker:
+
+  - Support changing the library search path. The system linker, when used
+    inside Android applications, is limited to the value of LD_LIBRARY_PATH
+    at boot time, that only looks into system directories, not application
+    ones.
+
+    This linker allows the client to add application paths before the
+    default system ones, this has two benefits:
+
+      - Library dependencies are loaded automatically in the right order.
+
+      - Libraries from the application paths are favored over system ones.
+        This avoids conflicts when one of your application's libraries
+        has the same name than a system one (which happens randomly
+        on certain devices due to system application bundling).
+
+    (Note: The system linker issue above has been fixed in Android 4.3).
+
+  - Supports any number of shared libraries. On older Android platforms,
+    the system linker will refuse to load more than 64 or 128 libraries
+    in a single process (Note: Fixed in Android 4.3).
+
+  - Supports loading a library at an explicit (page-aligned) memory
+    address. The system linker always randomizes the address. Note that
+    this is generally a _bad_ idea for security reasons. Consider using
+    this only when using shared RELROs (see below).
+
+  - Supports loading a library from an explicit (page-aligned) file
+    offset. This can be useful to load a library directly from an .apk,
+    provided that it is uncompressed and at a page-aligned offset.
+
+  - Support sharing of RELRO sections. When two processes load the same
+    library at exactly the same address, the content of its RELRO section
+    is identical. By default, each instance uses private RAM pages to host
+    it, but it is possible to use a single ashmem region to share the same
+    data instead.
+
+    WARNING: This feature will not work on certain older kernels. See
+             the documentation for crazy_system_can_share_relro() for
+             more details.
+
+See include/crazy_linker.h for the API and its documentation.
+
+See LICENSE file for full licensing details (hint: BSD)
+
+A few notes:
+
+  - Do not use this if you don't know what you're doing. Read the API
+    documentation first, and look at the test programs for usage examples.
+
+  - The crazy linker will always use the system linker to load NDK-exposed
+    system libraries (e.g. liblog.so and others). This avoids having two
+    instances of the same library in the same process, and correctly
+    resolving any symbols from system libraries.
+
+  - Any library loaded by the crazy linker, and which uses functions of
+    libdl.so will continue to work. However, calls to dlopen(), dlsym(),
+    et al will be redirected to the crazy linker's own wrappers.
+
+    This ensures that if a library is loaded by the crazy linker, any of
+    its dependencies will be loaded by it too.
+
+  - Libraries loaded with the crazy linker are visible to GDB, or Breakpad,
+    and stack unwinding / C++ exception propagation should just work.
+
+
+Caveats:
+--------
+
+  You can't call the crazy_linker code directly from Java in your Android
+  application (it's a static library). You need to put it into your own
+  shared library, loaded with System.loadLibrary() instead (or alternatively,
+  inside your NativeActivity's shared library).
+
+  Also, libraries loaded with the crazy linker are not visible to the system
+  one. In practice, it means that lazy native method lookup will not work. I.e.:
+
+  The first time you call a native method like:
+
+    'mypackage.MyClass.myNativeMethod()'
+
+  The VM will look into existing native libraries with dlsym() for a
+  function symbol named like:
+
+    Java_mypackage_MyClass_myNativeMethod
+
+  This will not work if the symbol is inside a library loaded with the
+  crazy_linker.
+
+  To work-around this, register the native methods explicitely
+  in your JNI_OnLoad() by calling env->RegisterNatives() with the
+  appropriate parameters.
+
+
+Usage instructions:
+-------------------
+
+  1/ Add the following to your module definition in your project's Android.mk:
+
+        LOCAL_STATIC_LIBRARIES := crazy_linker
+
+  2/ Also Include the top-level crazy_linker Android.mk, as in:
+
+        include /path/to/crazy_linker/Android.mk
+
+  3/ In your C or C++ source:
+
+        #include <crazy_linker.h>
+
+    Read the header for API documentation.
+
+  If your library implements native methods, it must explicitely register
+  them with env->RegisterNatives() before they become usable.
+
+BUGS & TODOs:
+-------------
+
+  - Libraries loaded by the crazy linker are not automatically closed when
+    the process exits.
+
+  - dlopen() when called inside a library loaded by the crazy linker doesn't
+    support RTLD_MAIN or RTLD_NEXT.
+
+Testing:
+--------
+
+  If you modify this code, check your changes by running the test suite using:
+
+    cd $NDK
+    tests/run-tests.sh crazy_linker
+
+  See DESIGN.TXT for an overview of the library's design.