From: Philippe Proulx Date: Wed, 17 Sep 2014 03:29:06 +0000 (-0400) Subject: Modernize README using Markdown X-Git-Tag: v2.6.0-rc1~12 X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=28ed962891cb7d32463aa9e8ced9d37a97eaea22;p=lttng-ust.git Modernize README using Markdown This commit also: * adds a project description at the top * simplifies the steps to build/link a user application with LTTng-UST and provides examples of commands * updates the Package contents list Signed-off-by: Philippe Proulx Signed-off-by: Mathieu Desnoyers --- diff --git a/Makefile.am b/Makefile.am index c907ff1b..b9a1115c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,6 +24,6 @@ SUBDIRS += tests doc pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = lttng-ust.pc -dist_doc_DATA = README ChangeLog +dist_doc_DATA = README.md ChangeLog dist_noinst_DATA = CodingStyle diff --git a/README b/README deleted file mode 100644 index 1d731ab7..00000000 --- a/README +++ /dev/null @@ -1,191 +0,0 @@ -LTTNG USERSPACE TRACER (LTTng-UST) ----------------------------- - -UST web site: http://lttng.org - -Updated versions of this package may be found at: - - * Releases: http://lttng.org/download - * GitWeb: http://git.lttng.org (project: lttng-ust) - * Git: git://git.lttng.org/lttng-ust.git - - -PREREQUISITES: - - - liburcu - Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney - - -> This release depends on liburcu v0.7.2 - - * Debian/Ubuntu package: liburcu-dev - * Website: http://lttng.org/urcu - * Releases: http://lttng.org/files/urcu - * GitWeb: http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary - * Git: git://git.urcu.so/userspace-rcu.git - -For developers using the git tree: - -This source tree is based on the autotools suite from GNU to simplify -portability. Here are some things you should have on your system in order to -compile the git repository tree : - -- GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50) - (make sure your system wide "automake" points to a recent version!) -- GNU Libtool >=2.2 - (for more information, go to http://www.gnu.org/software/autoconf/) -- Perl (optional) - Needed for make check and tests. - -If you get the tree from the repository, you will need to use the "bootstrap" -script in the root of the tree. It calls all the GNU tools needed to prepare the -tree configuration. - - -INSTALLATION INSTRUCTIONS: - - - Download, compile and install liburcu. - - In this package's tree, run ./configure. - - Run make. - - Run make install. - - Run ldconfig. - - If compiling from the git repository, run ./bootstrap before running - the configure script, to generate it. - - Note that configure sets '/usr/local' as the default prefix for files it - installs. However, this path is not part of most distributions' default - library path which will cause builds depending on liblttng-ust to fail unless - '-L/usr/local/lib' is added to LDFLAGS. You may provide a custom prefix to - configure by using the --prefix switch. Note that LTTng-UST needs to - be a shared library, even if the tracepoint probe provider is statically - linked into the application. - -USAGE: - - - Create an instrumentation header following the tracepoint examples. - See lttng/tracepoint.h, and examples. - - There are 2 ways to compile the Tracepoint Provider with the - application: either statically or dynamically. Please follow - carefully: - - 1.1) Compile the Tracepoint provider with the application, either - directly or through a static library (.a): - - Into exactly one object of your application: define - "TRACEPOINT_DEFINE" and include the tracepoint provider. - - Use "-I." for the compilation unit containing the tracepoint - provider include (e.g. tp.c). - - Link application with "-ldl" on Linux, with "-lc" on BSD. - - If building the provider directly into the application, - link the application with "-llttng-ust". - - If building a static library for the provider, link the static - library with "-llttng-ust". - - Include the tracepoint provider header into all C files using - the provider. - - Examples: - - doc/examples/easy-ust/ sample.c sample_component_provider.h - tp.c Makefile - - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h - Makefile - - 2) Compile the Tracepoint Provider separately from the application, - using dynamic linking: - - Into exactly one object of your application: define - "TRACEPOINT_DEFINE" _and_ also define - "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint - provider header. - - Include the tracepoint provider header into all instrumented C - files that use the provider. - - Compile the tracepoint provider with "-I.". - - Link the tracepoint provider with "-llttng-ust". - - Link application with "-ldl" on Linux, "-lc" on BSD. - - Set a LD_PRELOAD environment to preload the tracepoint provider - shared object before starting the application when tracing is - needed. Another way is to dlopen the tracepoint probe when needed - by the application. - - Example: - - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile - - - Note about dlclose() usage: it is not safe to use dlclose on a - provider shared object that is being actively used for tracing due - to a lack of reference counting from lttng-ust to the used shared - object. - - Enable instrumentation and control tracing with the "lttng" command - from lttng-tools. See lttng-tools doc/quickstart.txt. - - Note for C++ support: since LTTng-UST 2.3, both tracepoints and - tracepoint probes can be compiled in C++. To compile tracepoint probes - in C++, you need g++ >= 4.7 or Clang. - - -ENVIRONMENT VARIABLES: - - - liblttng-ust debug can be activated by setting the environment variable - "LTTNG_UST_DEBUG" when launching the application. It can also be enabled - at compile-time by compiling libust with -DLTTNG_UST_DEBUG. - - - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to - specify how long the applications should wait for sessiond - "registration done" command before proceeding to execute the main - program. The default is 3000ms (3 seconds). The timeout value is - specified in milliseconds. The value 0 means "don't wait". The value - -1 means "wait forever". Setting this environment variable to 0 is - recommended for applications with time constraints on the process - startup time. - - - The compilation flag "-DLTTNG_UST_DEBUG_VALGRIND" should be enabled - at build time to allow liblttng-ust to be used with valgrind - (side-effect: disables per-cpu buffering). - - -TRACE VIEWER: - - Use babeltrace for viewing traces generated by LTTng UST 2.x. - See http://lttng.org for download. - - -CONTACT: - - Maintainer: Mathieu Desnoyers - Mailing list: lttng-dev@lists.lttng.org - - -PACKAGE CONTENTS: - - This package contains the following elements. - - - liblttng-ust - The actual userspace tracing library that must be linked to the - instrumented programs. - - - include - The public header files that will be installed on the system. - - - tests - Various test programs - - - liblttng-ust-libc-wrapper - An example library that can be LD_PRELOAD'ed to instrument some - calls to libc (currently malloc() and free()) in any program without - need to recompile it. - - - liblttng-ust-fork - A library that is LD_PRELOAD'ed, and that hijacks calls to several system - calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed - in order to hijack calls. In contrast, libust may be linked at build time. - - - liblttng-ust-ctl - A library to control tracing in other processes. Used by lttng-tools. - - - liblttng-ust-comm - A static library shared between libust and lttng-tools, that - provides functions that allow these components to communicate together. - - - libringbuffer - The ring buffer implementation used within LTTng-UST. - - - snprintf - An asynchronous signal-safe version of snprintf. - - - liblttng-ust-java - A simple library that uses JNI to allow tracing in java programs. - See liblttng-ust-java/README for build instructions. diff --git a/README.md b/README.md new file mode 100644 index 00000000..e9ed8124 --- /dev/null +++ b/README.md @@ -0,0 +1,217 @@ +LTTng-UST +========= + +The LTTng User Space Tracing (LTTng-UST) library allows any C/C++ +application to be instrumented for and traced by +[LTTng](http://lttng.org/). LTTng-UST also includes a logging +back-end for Java applications and various dynamically loadable +user space tracing helpers for any application. + + +Prerequisites +------------- + +LTTng-UST depends on [liburcu](http://urcu.so/) v0.7.2 at build and +run times. + + +Building +-------- + +### Prerequisites + +This source tree is based on the Autotools suite from GNU to simplify +portability. Here are some things you should have on your system in order to +compile the Git repository tree: + + - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50, Autoheader >= 2.50; + make sure your system-wide `automake` points to a recent version!) + - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2 + - Perl (optional: needed for `make check` and tests) + +If you get the tree from the Git repository, you will need to run + + ./bootstrap + +in its root. It calls all the GNU tools needed to prepare the tree +configuration. + +To build LTTng-UST, do: + + ./configure + make + sudo make install + sudo ldconfig + +**Note:** the `configure` script sets `/usr/local` as the default prefix for +files it installs. However, this path is not part of most distributions' +default library path, which will cause builds depending on `liblttng-ust` +to fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a +custom prefix to `configure` by using the `--prefix` switch +(e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_ +the tracepoint probe provider is statically linked into the application. + + +Using +----- + +First of all, create an instrumentation header following the +[tracepoint examples](doc/examples). + +There are two ways to compile the tracepoint provider and link it with +your application: statically or dynamically. Please follow carefully one +or the other method. + + +### Static linking + +This method links the tracepoint provider with the application, +either directly or through a static library (`.a`): + + 1. Into exactly one unit (C/C++ source file) of your _application_, + define `TRACEPOINT_DEFINE` and include the tracepoint provider + header. + 2. Include the tracepoint provider header into all C/C++ files using + the provider and insert tracepoints using the `tracepoint()` macro. + 3. Use `-I.` when compiling the unit defining `TRACEPOINT_DEFINE` + (e.g., `tp.c`). + 4. Link the application with `-ldl` on Linux, or with `-lc` on BSD, + and with `-llttng-ust`. + +Example: + + gcc -c -I. tp.c + gcc -c some-source.c + gcc -c other-source.c + gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust + +Run the application directly: + + ./my-app + +Other relevant examples: + + - [`doc/examples/easy-ust`](doc/examples/easy-ust) + - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib) + + +### Dynamic loading + +This method decouples the tracepoint provider from the application, +making it dynamically loadable. + + 1. Into exactly one unit of your _application_, define + `TRACEPOINT_DEFINE` _and_ `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, + then include the tracepoint provider header. + 2. Include the tracepoint provider header into all C/C++ files using + the provider and insert tracepoints using the `tracepoint()` macro. + 3. Use `-I.` and `-fpic` when compiling the tracepoint provider + (e.g., `tp.c`). + 4. Link the tracepoint provider with `-llttng-ust` and make it a + shared object with `-shared`. + 5. Link the application with `-ldl` on Linux, or with `-lc` on BSD. + +Example: + + gcc -c -I. -fpic tp.c + gcc -o tp.so -shared tp.o -llttng-ust + gcc -o my-app some-source.c other-source.c -ldl + +To run _without_ LTTng-UST support: + + ./my-app + +To run with LTTng-UST support (register your tracepoint provider, +`tp.so`): + + LD_PRELOAD=./tp.so ./my-app + +You could also use `libdl` directly in your application and `dlopen()` +your tracepoint provider shared object (`tp.so`) to make LTTng-UST +tracing possible. + +Other relevant examples: + + - [`doc/examples/demo`](doc/examples/demo) + + +### Controlling tracing and viewing traces + +Use [LTTng-tools](https://lttng.org/download) to control the tracer. +Use [Babeltrace](https://lttng.org/babeltrace) to print traces as a +human-readable text log. + + +### Environment variables and compile flags + + - `liblttng-ust` debug can be activated by setting the environment + variable `LTTNG_UST_DEBUG` when launching the user application. It + can also be enabled at build time by compiling LTTng-UST with + `-DLTTNG_UST_DEBUG`. + - The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to + specify how long the applications should wait for the session + daemon _registration done_ command before proceeding to execute the + main program. The default is 3000 ms (3 seconds). The timeout value + is specified in milliseconds. The value 0 means _don't wait_. The + value -1 means _wait forever_. Setting this environment variable to 0 + is recommended for applications with time constraints on the process + startup time. + - The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled + at build time to allow `liblttng-ust` to be used with Valgrind + (side-effect: disables per-CPU buffering). + + +### Notes + +#### C++ support + +Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be +compiled in C++. To compile tracepoint probes in C++, you need +G++ >= 4.7 or Clang. + + +Contact +------- + +Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com) + +Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev) + + +Package contents +---------------- + +This package contains the following elements: + + - `doc`: LTTng-UST documentation and examples. + - `include`: the public header files that will be installed on the + system. + - `liblttng-ust`: the actual userspace tracing library that must be + linked to the instrumented programs. + - `liblttng-ust-comm`: a static library shared between `liblttng-ust` + and LTTng-tools, that provides functions that allow these components + to communicate together. + - `liblttng-ust-ctl`: a library to control tracing in other processes; + used by LTTng-tools. + - `liblttng-ust-cyg-profile`: a library that can be preloaded (using + `LD_PRELOAD`) to instrument function entries and exits when the target + application is built with the GCC flag `-finstrument-functions`. + - `liblttng-ust-dl`: a library that can be preloaded to instrument + calls to `dlopen()` and `dlclose()`. + - `liblttng-ust-fork`: a library that is preloaded and that hijacks + calls to several system calls in order to trace across these calls. + It _has_ to be preloaded in order to hijack calls. In contrast, + `liblttng-ust` may be linked at build time. + - `liblttng-ust-java`: a simple library that uses JNI to allow tracing + in Java programs. + - `liblttng-ust-jul`: a package that includes a JNI library and a JAR + library to provide an LTTng-UST logging back-end for Java application + using Java Util Logging. + - `liblttng-ust-libc-wrapper`: an example library that can be + preloaded to instrument some calls to libc (currently `malloc()` and + `free()`) and to POSIX threads (mutexes currently instrumented) in + any program without need to recompile it. + - `libringbuffer`: the ring buffer implementation used within LTTng-UST. + - `snprintf`: an asynchronous signal-safe version of `snprintf()`. + - `tests`: various test programs. + - `tools`: home of `lttng-gen-tp`.