Modernize README using Markdown
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Wed, 17 Sep 2014 03:29:06 +0000 (23:29 -0400)
committerMathieu Desnoyers <mathieu.desnoyers@efficios.com>
Wed, 17 Sep 2014 18:16:28 +0000 (14:16 -0400)
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 <eeppeliteloop@gmail.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Makefile.am
README [deleted file]
README.md [new file with mode: 0644]

index c907ff1b64ad306fab50e18b1495c49e905f1f54..b9a1115c136d16b3d795b88629812b08b1ac283b 100644 (file)
@@ -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 (file)
index 1d731ab..0000000
--- 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 <mathieu.desnoyers@efficios.com>
-  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 (file)
index 0000000..e9ed812
--- /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`.
This page took 0.029109 seconds and 4 git commands to generate.