X-Git-Url: http://git.liburcu.org/?p=lttng-ust.git;a=blobdiff_plain;f=README;h=78160a30f8210e0cdb9e8e6e8483aa3a6204e117;hp=746b1666fabb2de3ddcd3be4222a56f6494cb02e;hb=refs%2Fheads%2Fstable-2.0;hpb=f3049ad9e7b72287888452b9ed542c0f36e6eefe diff --git a/README b/README index 746b1666..78160a30 100644 --- a/README +++ b/README @@ -1,14 +1,14 @@ -LTTNG USERSPACE TRACER (UST) +LTTNG USERSPACE TRACER (LTTng-UST) ---------------------------- -UST web site and manual: http://lttng.org/ust +UST web site: http://lttng.org/lttng2.0 Updated versions of this package may be found at: - * Website: http://lttng.org/ust - * Releases: http://lttng.org/files/ust/releases - * GitWeb: http://git.lttng.org (project: ust) - * Git: git://git.lttng.org/ust.git + * Website: http://lttng.org/lttng2.0 + * Releases: http://lttng.org/files/lttng-ust + * GitWeb: http://git.lttng.org (project: lttng-ust) + * Git: git://git.lttng.org/lttng-ust.git PREREQUISITES: @@ -24,6 +24,21 @@ PREREQUISITES: * GitWeb: http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary * Git: git://lttng.org/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/) + +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: @@ -32,7 +47,6 @@ INSTALLATION INSTRUCTIONS: - Run make. - Run make install. - Run ldconfig. - - See the manual for usage instructions. If compiling from the git repository, run ./bootstrap before running the configure script, to generate it. @@ -41,9 +55,48 @@ INSTALLATION INSTRUCTIONS: USAGE: - Create an instrumentation header following the tracepoint examples. - (see tracepoint.h and tests/hello/tp.h). - - Link application with -lust. - - (TODO: start tracing with the "lttng" command from lttng-tools) + 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". + - 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 "-lllttng-ust". + - Include the tracepoint provider header into all C files using + the provider. + - Example: + tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example + + 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". + - 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: + - tests/demo/ demo.c tp*.c ust_tests_demo*.h demo-trace + + - Enable instrumentation and control tracing with the "lttng" command + from lttng-tools. See lttng-tools doc/quickstart.txt. ENVIRONMENT VARIABLES: @@ -56,7 +109,13 @@ ENVIRONMENT VARIABLES: "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". + -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: @@ -68,7 +127,7 @@ TRACE VIEWER: CONTACT: Maintainer: Mathieu Desnoyers - Mailing list: ltt-dev@lists.casi.polymtl.ca + Mailing list: lttng-dev@lists.lttng.org PACKAGE CONTENTS: @@ -82,15 +141,13 @@ PACKAGE CONTENTS: - include The public header files that will be installed on the system. - - doc - The documentation. - - tests Various test programs - - liblttng-ust-malloc - An example library that can be LD_PRELOAD'ed to instrument calls to malloc() - in any program without need to recompile it. + - 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 @@ -104,9 +161,12 @@ PACKAGE CONTENTS: 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. - - java + - liblttng-ust-java A simple library that uses JNI to allow tracing in java programs. - See java/README for build instructions. + See liblttng-ust-java/README for build instructions.