summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVivek Das Mohapatra <vivek@collabora.co.uk>2017-07-18 13:39:34 (GMT)
committerVivek Das Mohapatra <vivek@collabora.co.uk>2017-07-18 13:39:34 (GMT)
commit90b63b8a7e44f186213faaa7cc6919987f863324 (patch)
treeae3ecff50dc4f59b8a9d06febe504d8166b22ed9
parentde33b927ab3d07f82e3eb845fb40b44b36029a53 (diff)
downloadlibcapsule-90b63b8a7e44f186213faaa7cc6919987f863324.tar.gz
libcapsule-90b63b8a7e44f186213faaa7cc6919987f863324.tar.xz
Update the documentation to reflect the new out-of-tree proxy tooling
-rw-r--r--doc/Building.txt253
-rw-r--r--doc/Limitations.txt11
-rw-r--r--doc/Quick-Start.txt23
3 files changed, 189 insertions, 98 deletions
diff --git a/doc/Building.txt b/doc/Building.txt
index 4ea7758..00c9413 100644
--- a/doc/Building.txt
+++ b/doc/Building.txt
@@ -1,95 +1,176 @@
-Here we will outline the pieces necessary to build a libcapsule based
-library.
-
-At the moment libcapsule is still in its very early stages, so libraries
-that use libcapsule are built as part of libcapsule's build process.
-
-This will be broken out properly to allow external builds (technically
-it's possible right now but the details are not yet documented)
-
-Let us say we have a library libfoo.so.3.1 for which we wish to generate a
-capsule. We would need to make the following changes:
-
-============================================================================
-Makefile.am:
-
-Add a line like this with the other lib_LTLIBRARIES lines:
-
-lib_LTLIBRARIES += libfoo.la
-
-Then in the 'shim libraries' section:
-
-libfoo_la_SOURCES = shim/libfoo.so.c
-libfoo_la_LDFLAGS = -lcapsule -version-number 3:1:0
-
-Or, if the library in question uses versioned symbols:
-
-libfoo_la_SOURCES = shim/libfoo.so.c
-libfoo_la_LDFLAGS = -lcapsule -version-number 3:1:0 \
- -Wl,--version-script=shim/libfoo.so.map
-
-============================================================================
-
-shim/libfoo.so.c.excluded
-
-This file should contain a list of libraries which should _NOT_
-be picked up from the /host tree and isolated in the capsule,
-one per line.
-
-The following libraries are always considered to be excluded by
-the code generator, so there's no need to add them explicitly:
-
-libc.so.6
-libpthread.so.0
-libpthread-2.19.so
-libdl.so.2
-
-============================================================================
-
-shim/libfoo.so.c.shared
-
-This file should contain any extra libraries whose symbols should _also_ be
-exported from the capsule, along with those from the main library libfoo.so.
-
-It will generally be empty, but in libGL.so's case it contains:
-
-libxcb.so.1
-libxcb-glx.so.0
-libxcb-dri2.so.0
-libxcb-dri3.so.0
-libxcb-present.so.0
-libxcb-sync.so.1
-libX11.so
-
-If your _application_ (ie the program itself, NOT libfoo) links against any
-of these directly, it will likely also need the same shared libraries in the
-.shared file.
-
-============================================================================
-
+libcapsule provides a few tools to help initialise a proxy library project:
+
+The simplest route to a [hopefully] working project is as follows:
+
+ ~$ capsuletools=$(pkg-config --variable=libexecdir capsule)
+ ~$ $capsuletools/capsule-init-project libGL.so.1 /host
+
+ Generating project for /host : libGL.so.1 1.2.0 proxy
+ Creating project directory libGL-proxy
+ Working in /home/vivek/src/valve/dlmopen/libGL-proxy
+ Extracting dynamic symbols from /host : libGL.so.1
+ Preparing proxy source files
+ Initialising configure.ac
+ Initialising Makefile.am
+ Bootstrapping autoconf templates for libGL.so.1
+ Running initial configuration
+ autoreconf: Entering directory `.'
+ autoreconf: configure.ac: not using Gettext
+ autoreconf: running: aclocal --force
+ autoreconf: configure.ac: tracing
+ autoreconf: running: libtoolize --copy --force
+ libtoolize: putting auxiliary files in `.'.
+ libtoolize: copying file `./ltmain.sh'
+ libtoolize: putting macros in AC_CONFIG_MACRO_DIR, `m4'.
+ libtoolize: copying file `m4/libtool.m4'
+ libtoolize: copying file `m4/ltoptions.m4'
+ libtoolize: copying file `m4/ltsugar.m4'
+ libtoolize: copying file `m4/ltversion.m4'
+ libtoolize: copying file `m4/lt~obsolete.m4'
+ libtoolize: Consider adding `-I m4' to ACLOCAL_AMFLAGS in Makefile.am.
+ autoreconf: running: /usr/bin/autoconf --force
+ autoreconf: configure.ac: not using Autoheader
+ autoreconf: running: automake --add-missing --copy --force-missing
+ Makefile.am: installing './depcomp'
+ autoreconf: Leaving directory `.'
+ /home/x/src/valve/dlmopen/libGL-proxy is ready for ./configure, \
+ see README for details
+
+This will set up a project to build a proxy for libGL.so.1, expected
+to be found in a foreign filesystem tree mounted at /host.
+
+The target library (the real libGL.so.1) must be present in a well-formed
+tree mounted at /host at the point at which you run this command.
+
+If you ever make changes which require the proxy librayr source files
+to be regenerated (changing the foreign tree location from /host or
+altering the list of symbols to export) then the foreign tree must
+likewise be present.
+
+However you do not need the tree to be present to build the library itself
+once the project has been initialised.
+
+The layout of the project will be as follows:
+
+ ./
+ ./shim/
+ ./shim/libGL.so.c.shared
+ ./shim/libGL.so.c.dlopen
+ ./shim/libGL.so.symbols
+ ./shim/libGL.so.c.excluded
+ ./configure
+ ./m4/…
+ ./autom4te.cache/…
+ ./README
+ ./install-sh
+ ./depcomp
+ ./config.status
+ ./capsule-shim.mk
+ ./config.guess
+ ./Makefile
+ ./preconfigure.log
+ ./Makefile.am
+ ./configure.ac
+ ./config.sub
+ ./aclocal.m4
+ ./missing
+ ./config.log
+ ./libtool
+ ./ltmain.sh
+ ./compile
+ ./Makefile.in
+
+A few of these files are of immediate interest:
+----------------------------------------------------------------------------
+preconfigure.log:
+
+ This records the initial bootstrapping step of the project, which uses
+ autoconf to set up the build system from libcapsule's templates.
+
+ If things are working, there's little of interest here, but if something's
+ not quite right there may be important clues recorded here.
+----------------------------------------------------------------------------
+Makefile.am
+
+ A few important details are recorded here:
+
+ CAPSULE_LIBRARY - The stub of the library name (‘GL’ in this case).
+
+ CAPSULE_VERSION - The version number of the poxy library we should build
+ defaults to the same version as the library in /host
+ if that can be deduced from the /host tree.
+
+ Only the major version (major.minor.sub) needs to match,
+ otherwise you may change this as desired.
+
+ CAPSULE_TREE - The location of the foreign tree.
+
+ You may change this, but doing so requires the source
+ to be regenerated, which requires the new foreign tree
+ to be present.
+----------------------------------------------------------------------------
+shim/libGL.so.c.excluded
+
+ This file should contain a list of libraries which should _NOT_
+ be picked up from the /host tree and isolated in the capsule,
+ one per line.
+
+ The following library is always considered to be excluded by
+ the code generator, so there's no need to add it explicitly:
+
+ libdl.so.2
+
+ Other libraries which you may need to add, depending on the exact
+ API presented by the proxied library, are:
+
+ libc.so.6 - if memory allocated inside the target library
+ is freed by the main program, or similar.
+
+ libpthread.so.0 - if thread synchronisation or similar occurs
+ libpthread-2.19.so both inside the proxied library and your main
+ program AND the two need to be aware of one
+ another.
+
+
+----------------------------------------------------------------------------
+shim/libGL.so.c.shared
+
+ This file should contain any extra libraries whose symbols should _also_ be
+ exported from the capsule, along with those from the main library libGL.so.
+
+ It will generally be empty, but in libGL.so's case it must contain:
+
+ libxcb.so.1
+ libxcb-glx.so.0
+ libxcb-dri2.so.0
+ libxcb-dri3.so.0
+ libxcb-present.so.0
+ libxcb-sync.so.1
+ libX11.so
+----------------------------------------------------------------------------
shim/libfoo.so.c.dlopen
-If your library needs any special handling of dlopen() calls you will need to
-implement a function with the following signature and name:
-
-static void *_dlopen (const char *filename, int flags)
-{
- ⋮
-}
+ If your library needs any special handling of dlopen() calls you will need to
+ implement a function with the following signature and name:
-and put it in this file. If you do not, the default _dlopen wrapper generated
-by libcapsule's code generator will be installed instead.
+ static void *_dlopen (const char *filename, int flags)
+ {
+ ⋮
+ }
-Do NOT create an empty file with this name if you do not need libfoo-specific
-dlopen handling.
-
-============================================================================
-
-That's it - you should be ready to
+and put it in this file. A default wrapper which should work for most
+libraries is generated here by the capsule-init-project tool.
+----------------------------------------------------------------------------
+That's it - you should be ready to:
./configure
make
-Your generated capsule libraries (and libcapsule) will be in .libs
+Your generated capsule libraries will be in .libs,
+and you can use ‘make install’ et al, as usual, to install them.
+
+Note that you should be careful about this, as you are deliberately
+generating a library which has the same name as a ‘real’ one, which
+is very much not a normal situation, and carelessness here could break
+your system.
-============================================================================
diff --git a/doc/Limitations.txt b/doc/Limitations.txt
index 675d6c3..ca6a8b2 100644
--- a/doc/Limitations.txt
+++ b/doc/Limitations.txt
@@ -11,10 +11,10 @@ may not.
============================================================================
-There can only ever be one copy of libc, libpthread and libdl shared
-between the capsule and the public namespace. This behaviour is baked
-into the stub library generator script. Probably nothing particularly
-sane will happen if you try to ignore this limitation.
+There can only ever be one copy of libdl shared between the capsule
+and the public namespace. This behaviour is baked into the stub library
+generator script. Probably nothing particularly sane will happen if you
+try to ignore this limitation.
============================================================================
@@ -52,6 +52,7 @@ the dlmopen libc call (and the linker) to be modified.
If you are using Mesa before v 17.x you will need to use `patchelf' v0.9
or later to add a DT_NEEDED entry for libglapi.so.0 to your dri.so drivers
-in order for the libGL capsule to be able to work.
+in order for the libGL capsule to be able to work (assuming it is
+libGL.so tat you are trying to proxy).
============================================================================
diff --git a/doc/Quick-Start.txt b/doc/Quick-Start.txt
index 7ae04b9..8a74c2e 100644
--- a/doc/Quick-Start.txt
+++ b/doc/Quick-Start.txt
@@ -1,22 +1,31 @@
- In the top level directory:
+In the top level directory:
autoreconf -ivf
./configure
make
-libcapsule.so and capsules for libGL.so and libz.so will be in .libs/
-
-Currently make install probably won't do what you want: There are details
-yet to be thrashed out since libcapsule is atypical in that it deliberately
-creates libraries with the same name as existing ones: But you can copy.
+libcapsule.so will be in .libs/
The test environment is currently:
A chroot containing a debian/jessie filesystem with libGL.so removed,
-with the "real" OS filesystem bind mounted at /host.
+the libcapsule .deb installed and with the "real" OS filesystem bind
+mounted at /host.
In the chroot:
+Generate a proxy project for libGL:
+
+ ~$ capsuletools=$(pkg-config --variable=libexecdir capsule)
+ ~$ $capsuletools/capsule-init-project libGL.so.1 /host
+ ~$ cd libGL-proxy
+ ~$ extralib=".so.1 -glx.so.0 -dri2.so.0 -dri3.so.0 -present.so.0 -sync.so.1"
+ ~$ echo -n > shim/libGL.so.c.shared
+ ~$ for x in $extralib; do echo libxcb$x >> shim/libGL.so.c.shared; done
+ ~$ echo libX11.so >> shim/libGL.so.c.shared;
+ ~$ ./configure
+ ~$ make
+
Copy the generated libGL.so into an appropriate directory.
Ensure that ldd $(which glxgears) points to the libGL.so capsule