Meta-level run-time services for Unix processes... a.k.a. dragging Unix into the 1980s
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
contrib
include
lib
scripts
src
tests
tools
.gitignore
.gitmodules
.hgignore
.hgtags
LICENSE
LICENSE.gpl3
LICENSE.lgpl3
Makefile.am
README
autogen.sh
configure.ac
liballocs.pc.in

README

liballocs is a run-time library (and related toolchain extensions) which
somewhat-transparently adds a reflective notion of "allocations" to Unix
processes. 

To understand what that means, you probably have to read the paper
<http://www.cl.cam.ac.uk/~srk31/#onward15> from Onward! 2015. Or for a
brief introduction you could watch the talk from Strange Loop 2014.
<http://www.youtube.com/watch?v=LwicN2u6Dro>

Here are some things you'll need in order to build this software.

* C and C++ compilers supporting GNU C extensions
** gcc 4.9.x are known good
** gcc 7.2.x are known good
** gcc 5.x and 6.x are KNOWN BAD (bug 78407)
** clang has been known to work at various times....
* GNU make 3.81 or later
* GNU bash
* autoconf 2.69 or greater
* automake 1.11 or greater
* libtool
* pkg-config
* autoconf-archive
* boost 1.55 or later (1.55 is "known good" as of this writing)
* libelfg0 (i.e. the elfutils implementation)
* OCaml 4.01.0 or newer
* a Java 6 (or newer) runtime 
* libunwind

There are also a lot of dependencies on my other codebases. These are
now included as git submodules under contrib/, so you can try the (new)
"impatient" method for building, as follows.

Next, you must have GNU binutils 2.26 or later. In fact, for a
fully-functioning liballocs toolchain, you'll also want my *patched*
binutils. You can get a long way without it, so this step is optional,
but in some awkward cases, liballocs's compilers wrappers need to
invoke my hacked objcopy. Also, Debian jessie's binutils 2.25 is too
old to build the liballocs linker plugin (also optional), adding extra
motivation to do this step. (I will remove this requirement
eventually.) For now, assuming you're grabbing my code from my GitHub
page:

$ sudo apt-get install bison flex texinfo
$ git clone https://github.com/stephenrkell/binutils-gdb.git
$ cd binutils-gdb
$ CFLAGS="-fPIC -g -O2" ./configure --prefix=/usr/local \
      --enable-gold --enable-plugins --enable-install-libiberty \
# a PIC libbfd.a and co-lo'd libiberty helps e.g. build OProfile
$ make -jn                    # for your favourite n
$ sudo make install

Now you should have my patched objcopy on your PATH... it defines an
option --unbind-sym, if you want to check.

Then on Debian-based systems, proceed like so (tested on jessie and
stretch)....

$ sudo apt-get install libelfg0-dev \
    autoconf automake libtool pkg-config autoconf-archive \
    g++ ocaml ocaml-findlib \
    default-jre-headless \
    make git gawk gdb \
    libunwind-dev libc6-dev-i386 zlib1g-dev libc6-dbg \
    libboost-{iostreams,regex,serialization,filesystem}-dev
$ git clone https://github.com/stephenrkell/liballocs.git
$ cd liballocs
$ git submodule init
$ git submodule update
$ make -C contrib -jn         # for your favourite n
$ ./autogen.sh
$ . contrib/env.sh
$ ./configure --prefix=/usr/local
$ make -jn                    # for your favourite n

You will also want to set up space to hold metadata files.

$ cd ..
$ export LIBALLOCS=`pwd`/liballocs
$ sudo mkdir /usr/lib/meta # metadata will live here
$ sudo chown root:staff /usr/lib/meta
$ sudo chmod g+w /usr/lib/meta
$ make -f "$LIBALLOCS"/tools/Makefile.meta \
  /usr/lib/meta$( readlink -f /lib/x86_64-linux-gnu/libc.so.6 )-meta.so

If you've got this far, you may as well run the tests.

$ cd liballocs/tests
$ make                        # please report any failures to me

That's it! Enjoy liballocs and do fun things with it.

There are now also some LLVM/clang-based versions of the tools. If you
want them:

$ make -C contrib llvm
$ make llvm

... but be aware that they're a work in progress!