refactor: libaustin

.github/workflows/benchmarks.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Compile Austin
         run: |
           autoreconf --install
-          ./configure --enable-debug-symbols true
+          ./configure --enable-debug-symbols=yes
           make
 
       - name: Install runtime dependencies

.github/workflows/release.yml

@@ -26,7 +26,7 @@ jobs:
           pip install -r scripts/requirements-bw.txt
           
           sudo apt-get update
-          sudo apt-get -y install autoconf build-essential libunwind-dev binutils-dev libiberty-dev musl-tools zlib1g-dev
+          sudo apt-get -y install autoconf build-essential libunwind-dev binutils-dev libiberty-dev musl-tools zlib1g-dev libtool
 
           # Build austin
           autoreconf --install
@@ -38,6 +38,10 @@ jobs:
           pushd src
           tar -Jcf austin-$VERSION-gnu-linux-amd64.tar.xz austin
           tar -Jcf austinp-$VERSION-gnu-linux-amd64.tar.xz austinp
+
+          cp ../include/libaustin.h .
+          cp .libs/libaustin.{a,so.*.*} .
+          tar -Jcf libaustin-$VERSION-gnu-linux-amd64.tar.xz libaustin.*
           popd
 
           # Build gnu wheel
@@ -47,7 +51,7 @@ jobs:
             --files austin:src/austin austinp:src/austinp
 
           # Build with musl
-          musl-gcc -O3 -Os -s -Wall -pthread src/*.c -o src/austin -D__MUSL__
+          musl-gcc -O3 -Os -s -Wall -pthread src/*.c -Iinclude -o src/austin -D__MUSL__
           pushd src
           tar -Jcf austin-$VERSION-musl-linux-amd64.tar.xz austin
           popd
@@ -64,7 +68,7 @@ jobs:
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: src/austin*.tar.xz
+          file: src/*austin*.tar.xz
           tag: ${{ github.ref }}
           overwrite: true
           file_glob: true

.github/workflows/release_arch.yml

@@ -35,7 +35,7 @@ jobs:
         uses: svenstaro/upload-release-action@v2
         with:
           repo_token: ${{ secrets.GITHUB_TOKEN }}
-          file: artifacts/austin*.tar.xz
+          file: artifacts/*austin*.tar.xz
           tag: ${{ github.ref }}
           overwrite: true
           file_glob: true

.github/workflows/tests.yml

@@ -20,12 +20,12 @@ jobs:
 
       - name: Install build dependencies
         run: |
-          sudo apt-get -y install libunwind-dev binutils-dev libiberty-dev
+          sudo apt-get -y install libunwind-dev binutils-dev libiberty-dev libtool
 
       - name: Compile Austin
         run: |
           autoreconf --install
-          ./configure --enable-debug-symbols true
+          ./configure --enable-debug-symbols=yes
           make
 
       - uses: actions/upload-artifact@v3
@@ -34,6 +34,7 @@ jobs:
           path: |
             src/austin
             src/austinp
+            src/.libs/libaustin.so*
 
   build-linux-musl:
     runs-on: ubuntu-20.04    
@@ -47,7 +48,7 @@ jobs:
 
       - name: Compile Austin
         run: |
-          musl-gcc -O3 -Os -s -Wall -pthread src/*.c -o src/austin.musl -D__MUSL__
+          musl-gcc -O3 -Os -s -Wall -pthread src/*.c -Iinclude -o src/austin.musl -D__MUSL__
 
       - uses: actions/upload-artifact@v3
         with:
@@ -156,7 +157,7 @@ jobs:
       - uses: actions/checkout@v2
 
       - name: Compile Austin
-        run: gcc-11 -Wall -Werror -O3 -g src/*.c -o src/austin
+        run: gcc-11 -Wall -Werror -O3 -g src/*.c -Iinclude -o src/austin
 
       - uses: actions/upload-artifact@v3
         with:
@@ -275,7 +276,7 @@ jobs:
       - name: Compile Austin
         run: |
           gcc.exe --version
-          gcc.exe -O3 -g -o src/austin.exe src/*.c -lpsapi -lntdll -Wall -Werror
+          gcc.exe -O3 -g -o src/austin.exe src/*.c -Iinclude -lpsapi -lntdll -Wall -Werror
           src\austin.exe --help
 
       - uses: actions/upload-artifact@v3
@@ -391,7 +392,7 @@ jobs:
       - name: Compile Austin
         run: |
           autoreconf --install
-          ./configure --enable-debug-symbols true
+          ./configure --enable-debug-symbols=yes
           make
 
       - name: Install runtime dependencies

.gitignore

@@ -39,6 +39,7 @@ src/austin
 src/austinp
 src/austin.exe
 
+.libs/
 
 # -----------------------------------------------------------------------------
 # --  PYTHON SOURCES

Dockerfile

@@ -1,7 +1,7 @@
 FROM  ubuntu:20.04
 COPY  . /austin
 RUN   apt-get update && \
-      apt-get install -y autoconf build-essential libunwind-dev binutils-dev libiberty-dev zlib1g-dev && \
+      apt-get install -y autoconf build-essential libunwind-dev binutils-dev libiberty-dev zlib1g-dev libtool && \
       cd /austin && \
       autoreconf --install && \
       ./configure && \

README.md

@@ -293,19 +293,19 @@ git clone --depth=1 https://github.com/P403n1x87/austin.git
 On Linux, one can then use the command
 
 ~~~ console
-gcc -O3 -Os -Wall -pthread src/*.c -o src/austin
+gcc -O3 -Os -Wall -pthread src/*.c -Iinclude -o src/austin
 ~~~
 
 whereas on macOS it is enough to run
 
 ~~~ console
-gcc -O3 -Os -Wall src/*.c -o src/austin
+gcc -O3 -Os -Wall src/*.c -Iinclude -o src/austin
 ~~~
 
 On Windows, the `-lpsapi -lntdll` switches are needed
 
 ~~~ console
-gcc -O3 -Os -Wall -lpsapi -lntdll src/*.c -o src/austin
+gcc -O3 -Os -Wall -lpsapi -lntdll src/*.c -Iinclude -o src/austin
 ~~~
 
 Add `-DDEBUG` if you need a more verbose log. This is useful if you encounter a
@@ -521,7 +521,7 @@ sudo apt install libunwind-dev binutils-dev
 and compile with
 
 ~~~ console
-gcc -O3 -Os -Wall -pthread src/*.c -DAUSTINP -lunwind-ptrace -lunwind-generic -lbfd -o src/austinp
+gcc -O3 -Os -Wall -pthread src/*.c -Iinclude -DAUSTINP -lunwind-ptrace -lunwind-generic -lbfd -o src/austinp
 ~~~
 
 then use as per normal. The extra `-k/--kernel` option is available with
@@ -557,6 +557,70 @@ show both native and Python frames. Highlighting helps tell frames apart. The
 > executable will be available as `austin.p` from the command line.
 
 
+## libaustin
+
+The code base can also be used to generate a library to embed Austin in your
+projects to unwind Python stacks or extract frame information from a running
+Python process.
+
+A shared library on Linux can be obtained with
+
+~~~ console
+gcc -O3 -Wall -pthread src/*.c -Iinclude -o src/libaustin.so -shared -fPIC -DLIBAUSTIN
+~~~
+
+The required headers are in the `include/` subfolder. More information on how
+to use the library can be found in the `libaustin.h` header file.
+
+At a glance, this is a typical use. The library needs to be initialised at
+runtime before it can be used. Hence, before you call any other of the exported
+functions, you must do
+
+~~~ c
+#include <libaustin.h>
+
+...
+
+{
+  ...
+
+  austin_up();
+
+  ...
+}
+~~~
+
+After this call, you can attach any Python process with
+
+~~~ c
+pid_t pid = ...;
+...
+austin_handle_t proc_handle = austin_attach(pid);
+~~~
+
+When you want to sample the call stack of an attached process, call
+
+~~~ c
+austin_sample(proc_handle, cb);
+~~~
+
+where `cb` is a callback function with signature `void ()(pid_t pid, pid_t tid)`
+that gets called once a thread stack is ready to be retrieved. To get the frames
+from the sampled stack, call `austin_pop_frame()` until it returns `NULL`.
+
+To sample a single thread, use `austin_sample_thread(proc_handle, tid)` instead.
+Then retrieve the sampled stack with `austin_pop_frame()` as above.
+
+Once you are done with the process, you should detach it with
+
+~~~ c
+austin_detach(proc_handle);
+~~~
+
+Once you are done with libaustin entirely, make sure to release resources with
+`austin_down()`.
+
+
 ## Logging
 
 Austin uses `syslog` on Linux and macOS, and `%TEMP%\austin.log` on Windows

configure.ac

@@ -16,6 +16,9 @@ AM_INIT_AUTOMAKE
 AC_PROG_CC_C99
 AC_PROG_CPP
 
+# Use libtool for libaustin.
+LT_INIT
+
 # Use the C language and compiler for the following checks
 AC_LANG([C])