Skip to content
GitLab
Explore
Sign in
Register
Primary navigation
Search or go to…
Project
steam-runtime-tools
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Package registry
Model registry
Operate
Environments
Terraform modules
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
steamrt
steam-runtime-tools
Commits
90b63b8a
Commit
90b63b8a
authored
7 years ago
by
Vivek Das Mohapatra
Browse files
Options
Downloads
Patches
Plain Diff
Update the documentation to reflect the new out-of-tree proxy tooling
parent
de33b927
No related branches found
No related tags found
1 merge request
!311
Build capsule-capture-libs from a bundled copy of libcapsule
Changes
3
Hide whitespace changes
Inline
Side-by-side
Showing
3 changed files
doc/Building.txt
+167
-86
167 additions, 86 deletions
doc/Building.txt
doc/Limitations.txt
+6
-5
6 additions, 5 deletions
doc/Limitations.txt
doc/Quick-Start.txt
+16
-7
16 additions, 7 deletions
doc/Quick-Start.txt
with
189 additions
and
98 deletions
doc/Building.txt
+
167
−
86
View file @
90b63b8a
Here we will outline the pieces necessary to build a libcapsule based
libcapsule provides a few tools to help initialise a proxy library project:
library.
The simplest route to a [hopefully] working project is as follows:
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.
~$ capsuletools=$(pkg-config --variable=libexecdir capsule)
~$ $capsuletools/capsule-init-project libGL.so.1 /host
This will be broken out properly to allow external builds (technically
it's possible right now but the details are not yet documented)
Generating project for /host : libGL.so.1 1.2.0 proxy
Creating project directory libGL-proxy
Let us say we have a library libfoo.so.3.1 for which we wish to generate a
Working in /home/vivek/src/valve/dlmopen/libGL-proxy
capsule. We would need to make the following changes:
Extracting dynamic symbols from /host : libGL.so.1
Preparing proxy source files
============================================================================
Initialising configure.ac
Makefile.am:
Initialising Makefile.am
Bootstrapping autoconf templates for libGL.so.1
Add a line like this with the other lib_LTLIBRARIES lines:
Running initial configuration
autoreconf: Entering directory `.'
lib_LTLIBRARIES += libfoo.la
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force
Then in the 'shim libraries' section:
autoreconf: configure.ac: tracing
autoreconf: running: libtoolize --copy --force
libfoo_la_SOURCES = shim/libfoo.so.c
libtoolize: putting auxiliary files in `.'.
libfoo_la_LDFLAGS = -lcapsule -version-number 3:1:0
libtoolize: copying file `./ltmain.sh'
libtoolize: putting macros in AC_CONFIG_MACRO_DIR, `m4'.
Or, if the library in question uses versioned symbols:
libtoolize: copying file `m4/libtool.m4'
libtoolize: copying file `m4/ltoptions.m4'
libfoo_la_SOURCES = shim/libfoo.so.c
libtoolize: copying file `m4/ltsugar.m4'
libfoo_la_LDFLAGS = -lcapsule -version-number 3:1:0 \
libtoolize: copying file `m4/ltversion.m4'
-Wl,--version-script=shim/libfoo.so.map
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
shim/libfoo.so.c.excluded
autoreconf: running: automake --add-missing --copy --force-missing
Makefile.am: installing './depcomp'
This file should contain a list of libraries which should _NOT_
autoreconf: Leaving directory `.'
be picked up from the /host tree and isolated in the capsule,
/home/x/src/valve/dlmopen/libGL-proxy is ready for ./configure, \
one per line.
see README for details
The following libraries are always considered to be excluded by
This will set up a project to build a proxy for libGL.so.1, expected
the code generator, so there's no need to add them explicitly:
to be found in a foreign filesystem tree mounted at /host.
libc.so.6
The target library (the real libGL.so.1) must be present in a well-formed
libpthread.so.0
tree mounted at /host at the point at which you run this command.
libpthread-2.19.so
libdl.so.2
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.
shim/libfoo.so.c.shared
However you do not need the tree to be present to build the library itself
This file should contain any extra libraries whose symbols should _also_ be
once the project has been initialised.
exported from the capsule, along with those from the main library libfoo.so.
The layout of the project will be as follows:
It will generally be empty, but in libGL.so's case it contains:
./
libxcb.so.1
./shim/
libxcb-glx.so.0
./shim/libGL.so.c.shared
libxcb-dri2.so.0
./shim/libGL.so.c.dlopen
libxcb-dri3.so.0
./shim/libGL.so.symbols
libxcb-present.so.0
./shim/libGL.so.c.excluded
libxcb-sync.so.1
./configure
libX11.so
./m4/…
./autom4te.cache/…
If your _application_ (ie the program itself, NOT libfoo) links against any
./README
of these directly, it will likely also need the same shared libraries in the
./install-sh
.shared file.
./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
shim/libfoo.so.c.dlopen
If your library needs any special handling of dlopen() calls you will need to
If your library needs any special handling of dlopen() calls you will need to
implement a function with the following signature and name:
implement a function with the following signature and name:
static void *_dlopen (const char *filename, int flags)
{
⋮
}
and put it in this file. If you do not, the default _dlopen wrapper generated
static void *_dlopen (const char *filename, int flags)
by libcapsule's code generator will be installed instead.
{
⋮
}
Do NOT create an empty file with this name if you do not need libfoo-specific
and put it in this file. A default wrapper which should work for most
dlopen handling.
libraries is generated here by the capsule-init-project tool.
----------------------------------------------------------------------------
============================================================================
That's it - you should be ready to:
That's it - you should be ready to
./configure
./configure
make
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.
============================================================================
This diff is collapsed.
Click to expand it.
doc/Limitations.txt
+
6
−
5
View file @
90b63b8a
...
@@ -11,10 +11,10 @@ may not.
...
@@ -11,10 +11,10 @@ may not.
============================================================================
============================================================================
There can only ever be one copy of lib
c, libpth
re
a
d
and libdl shared
There can only ever be one copy of lib
dl sha
red
between the capsule
between the capsule
and the public namespace. This behaviour is baked
and the public namespace. This behaviour is baked
into the stub library
into the stub library
generator script. Probably nothing particularly
generator script. Probably nothing particularly
sane will happen if you
sane will happen if you
try to ignore this limitation.
try to ignore this limitation.
============================================================================
============================================================================
...
@@ -52,6 +52,7 @@ the dlmopen libc call (and the linker) to be modified.
...
@@ -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
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
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).
============================================================================
============================================================================
This diff is collapsed.
Click to expand it.
doc/Quick-Start.txt
+
16
−
7
View file @
90b63b8a
In the top level directory:
In the top level directory:
autoreconf -ivf
autoreconf -ivf
./configure
./configure
make
make
libcapsule.so and capsules for libGL.so and libz.so will be in .libs/
libcapsule.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.
The test environment is currently:
The test environment is currently:
A chroot containing a debian/jessie filesystem with libGL.so removed,
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:
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.
Copy the generated libGL.so into an appropriate directory.
Ensure that ldd $(which glxgears) points to the libGL.so capsule
Ensure that ldd $(which glxgears) points to the libGL.so capsule
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment