From 0cac4892ffe32de293c9690387629e9fd8395c99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vivek=20Das=C2=A0Mohapatra?= <vivek@collabora.co.uk>
Date: Thu, 18 May 2017 18:10:16 +0100
Subject: [PATCH] Populate the README file

---
 README | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)

diff --git a/README b/README
index e69de29bb..049a6f689 100644
--- a/README
+++ b/README
@@ -0,0 +1,111 @@
+This directory contains the sources of libcapsule.
+
+NB: Apparently there's a libcapsule to do with figuring out
+which audio and video APIs a game uses. This isn't that.
+We may have to change the project's name or something.
+────────────────────────────────────────────────────────────────────────────
+So what is it?
+
+libcapsule is a helper library that allows the construction of a `capsule'
+library - a sort of proxy library that contains one or more shared libraries
+but only exposes a requested set of symbols to the program or library that
+links to it [the capsule].
+
+libcapsule is designed to be used to create a library with the same name
+as one of the libraries needed by another ELF object, and placed in the
+filesystem such that it would be found by the linker instead of the "real"
+library. It then picks up the "real" libraries for which it proxies using
+a simplified version of the linker's library location algorithm and rewrites
+the symbol tables in all currently loaded ELF objects to point to the "real"
+function symbols.
+
+This source tree contains working examples for libGL.so and libz.so:
+
+  The libGL.so capsule has been tested with glxinfo & glxgears.
+  The libz.so capsule has been tested with bsdtar.
+────────────────────────────────────────────────────────────────────────────
+Why would I want this?
+
+In an ideal world, you would never want this.
+
+However this is not that world.
+
+Sometimes shared libraries have conflicting requirements. The original
+problem that set this project in motion was incompatible libstdc++
+requirements between games and the Mesa DRI drivers:
+
+Games built against one version of libstdc++ might not be able to tolerate
+the (often much newer) libstdc++ pulled in by a Mesa driver (such as
+i965_dri.so).
+
+libcapsule allows you to partition off the dependencies of certain libraries,
+so you get only the symbols from that library and do not see those of its
+dependencies.
+
+This does rely on (for example) an object allocated or managed by the
+encapsulated libstdc++ never being deleted or managed by the libstdc++
+that the application outside the capsule sees - fortunately the GL API
+does not expose us to that problem. See doc/Limitations.txt for more
+details.
+────────────────────────────────────────────────────────────────────────────
+How does it work?
+
+A simplified version of what goes on in the libGL capsule (details below)
+
+                          ┌────────────────┐
+               ┌─────────>│ gl─application │<─────────┬─────────┬───┐
+               │          └────────────────┘          │         │   │
+               │                                      │         │   │
+      ┌────────┴──────────┐   ┌───────────────┐       │         │   │
+      │ libGL.so(capsule) │<──┤ libcapsule.so │       │         │   │
+      └───────────────────┘   └───────────────┘       │         │   │
+                     ↑                                │         │   │
+   ┌─────────────────│───────┐                        │         │   │
+   │    from /host   │       │               from /   │         │   │
+   │  ┌──────────────┴────┐  │          ┌─────────────┴──┐      │   │
+   │  │ libxcb.so.1    *  │<──────┐     │ misc libraries │      │   │
+   │  ├───────────────────┤  │    │     └────────────────┘      │   │
+   │  │ libX11.so      *  │<──────┤                             │   │
+   │  ├───────────────────┤  │    │     ┌─────────────────┐     │   │
+   │  │ libGL.so.1     *  │<──────┤     │ libstdc++.so    ├─────┘   │
+   │  └───────────────────┘  │    │     └─────────────────┘         │
+   │           ↿⇂            │    │                                 │
+   │  ┌───────────────────┐  │    │     ┌─────────────────┐         │
+   │  │ Mesa DRI driver   │<──────┴─────│ libc.so.6       ├─────────┘
+   │  └───────────────────┘  │          └─────────────────┘
+   │           ↑             │
+   │  ┌────────┴──────────┐  │
+   │  │ libstdc++.so      │  │
+   │  └───────────────────┘  │
+   │                         │
+   └─────────────────────────┘
+
+In the setup shown above, we have a 'runtime' rooted at / which contains
+a set of shared libraries, the dynamic linker, and the libGL.so capsule
+(but no real libGL.so).
+
+Mounted into the runtime at /host is the "real" OS filesystem tree.
+The mechanism is unimportant here: It could be bwrap (bubblewrap)
+or the real / bind-mounted into a chroot, or some other approach.
+
+The libGL capsule is configured (at build time) to expose only the symbols
+from libxcb, libX11 and libGL to gl-application (and the other shared
+libraries pulled in by gl-application if they use any of those symbols).
+
+Any symbols from copies of libxcb, libX11 etc which are pulled in from
+the runtime tree at / will be masked by libcapsule with the symbols
+from the /host copies of those libraries.
+
+For practical reasons, libc.so.6 must be shared by both the capsule
+libraries and the runtime ones.
+
+Any symbols _not_ flagged explicitly for export from the capsule
+will not be visible to gl-application or the other libraries from
+the runtime: This permits a potentially incompatible libstdc++.so
+from the runtime to coexist with the one pulled in from the /host
+tree by the Mesa DRI driver.
+
+────────────────────────────────────────────────────────────────────────────
+
+For more details on the mechanics of the capsule and/or how to modify
+an existing capsule or add your own see the doc/ directory.
-- 
GitLab