Modernize README with Markdown
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Wed, 17 Sep 2014 19:33:10 +0000 (15:33 -0400)
committerDavid Goulet <dgoulet@efficios.com>
Tue, 30 Sep 2014 18:28:50 +0000 (14:28 -0400)
This commit also:

  * adds a project description at the top
  * fixes a few grammar mistakes here and there
  * updates the Package contents list

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: David Goulet <dgoulet@efficios.com>
INSTALL
README [deleted file]
README.md [new file with mode: 0644]
doc/quickstart.txt
doc/streaming-howto.txt

diff --git a/INSTALL b/INSTALL
index 7d1c323beae76333f523f6df31c47a87f5597edb..e146eab3d6c1142b3399bfa0261c2da448c0ca46 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -14,7 +14,7 @@ Basic Installation
 
    Briefly, the shell commands `./configure; make; make install' should
 configure, build, and install this package.  The following
-more-detailed instructions are generic; see the `README' file for
+more-detailed instructions are generic; see the `README.md' file for
 instructions specific to this package.  Some packages provide this
 `INSTALL' file but do not implement all of the features documented
 below.  The lack of an optional feature in a given package is not
@@ -38,7 +38,7 @@ cache files.
 
    If you need to do unusual things to compile the package, please try
 to figure out how `configure' could check whether to do them, and mail
-diffs or instructions to the address given in the `README' so they can
+diffs or instructions to the address given in the `README.md' so they can
 be considered for the next release.  If you are using the cache, and at
 some point `config.cache' contains results you don't want to keep, you
 may remove or edit it.
@@ -200,8 +200,8 @@ option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
 `configure', where FEATURE indicates an optional part of the package.
 They may also pay attention to `--with-PACKAGE' options, where PACKAGE
 is something like `gnu-as' or `x' (for the X Window System).  The
-`README' should mention any `--enable-' and `--with-' options that the
-package recognizes.
+`README.md' should mention any `--enable-' and `--with-' options that
+the package recognizes.
 
    For packages that use the X Window System, `configure' can usually
 find the X include and library files automatically, but if it doesn't,
diff --git a/README b/README
deleted file mode 100644 (file)
index 43fd0c5..0000000
--- a/README
+++ /dev/null
@@ -1,187 +0,0 @@
-LTTng Trace Control
-----------------
-
-Please visit https://lttng.org for more information. The current maintainer is
-David Goulet <dgoulet@efficios.com>.
-
-Latest development can be found at:
-
-    * Gitweb :  https://git.lttng.org/?p=lttng-tools.git;a=summary
-    * Git :     git://git.lttng.org/lttng-tools.git
-
-REQUIREMENTS:
-
-    - Linux kernel >= 2.6.27
-      For epoll() support, at least this version is needed. However, poll() is
-      also supported by running "./configure --disable-epoll". Using that, the
-      kernel version can probably be older but we can't provide any guarantee.
-      Please let us know if you are able to go lower without any problems.
-
-    - liburcu >= 0.8.0
-      Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney
-
-      -> Tested with liburcu 0.8.x stable.
-
-      * Debian/Ubuntu package: liburcu-dev
-      * Git : git://git.lttng.org/userspace-rcu.git
-      * Website:  https://lttng.org/urcu
-
-    - libpopt >= 1.13
-      Library for parsing command line parameters
-
-      * Debian/Ubuntu package: libpopt-dev
-
-    - libuuid
-      Universally unique id library
-
-      * Debian/Ubuntu package: uuid-dev
-
-    - Babeltrace (optional)
-      Trace viewer. Enable the use of "lttng view" command
-
-      * Debian/Ubuntu package: babeltrace
-
-    - libxml2 >= 2.7.6
-      XML document parsing library.
-
-      * Debian/Ubuntu package: libxml2-dev
-
-    - Perl (optional)
-      Needed for make check and tests.
-
-    - Python >= 3.0 (optional)
-      Needed for make check and tests.
-
-      * Debian/Ubuntu package: python3
-
-    - SWIG >= 2.0 (optional)
-      Needed for Python bindings (--enable-python-bindings).
-
-      * Debian/Ubuntu package: swig2.0
-
-    - python-dev (optional)
-      Python headers
-
-      * Debian/Ubuntu package: python3-dev
-
-    - For kernel tracing: modprobe
-
-    - bash
-      Needed for running "make check".
-
-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 https://www.gnu.org/software/autoconf/)
-- flex >= 2.5.35
-- bison >= 2.4
-
-If you use GNU gold, which is NOT mandatory, make sure you have this version:
-- GNU gold >= 2.22
-(Before this version we hit a known bug documented at:
- http://sourceware.org/bugzilla/show_bug.cgi?id=11317)
-Be advise that with GNU gold, you'll might have to specify -L/usr/local/lib in
-LDFLAGS.
-
-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 the prerequisites.
-  Then:
-  $ ./boostrap
-  $ ./configure
-  $ make
-  $ sudo make install
-  $ sudo ldconfig
-
-  If compiling from the git repository, run ./bootstrap before running
-  the configure script, to generate it.
-
-  If you want Python bindings, run ./configure --enable-python-bindings.
-  Please note that some distributions will need the following
-  environment variables set before running configure:
-
-    export PYTHON="python3"
-    export PYTHON_CONFIG="/usr/bin/python3-config"
-
-USAGE:
-
-Please see doc/quickstart.txt to help you start tracing. You can also use the
--h/--help command on 'lttng' and all other commands offered in this tool (Ex:
-lttng enable-event -h).
-
-A network streaming HOWTO can be found in doc/streaming-howto.txt which quickly
-helps you understand how to stream a LTTng 2.0 trace.
-
-A Python HOWTO can be found in doc/python-howto.txt which quickly
-helps you understand how to use the Python module to control the LTTng API.
-
-PACKAGE CONTENTS:
-
-    This package contains the following elements:
-
-    - liblttng-ctl (public API)
-      The LTTng tracing control library.
-
-    - libsessiond-comm (internal)
-      The lttng-sessiond communication library. In order to talk with
-      lttng-sessiond, this library must be used.
-
-    - libkernel-ctl (internal)
-      Kernel tracer control and ioctl definitions.
-
-    - libconsumer (internal)
-      Library for Kernel and (optionally) UST trace consumer.
-
-    - libkernel-consumer (internal)
-      Library for Kernel consumer control
-
-    - libust-consumer (internal)
-      Library for UST consumer control
-
-    - libhashtable (internal)
-      Library wrapper over URCU hashtables.
-
-    - libcommon (internal)
-      Contains multiple useful function call used by the whole tree.
-
-    - libcompat (internal)
-      Compatibility library mostly for FreeBSD and Linux.
-
-    - librelayd (internal)
-      Library for all relayd interactions over the network.
-
-    - lttng-relayd
-      The relay daemon used for network streaming
-
-    - lttng-consumerd
-      The consumer daemon which uses libconsumer.
-
-    - lttng-sessiond
-      The LTTng session daemon binary.
-
-    - lttng
-      The LTTng tracer command line control tool.
-
-    - include (installed in $(includedir)/lttng/)
-      The liblttngctl API header file.
-
-    - tests
-      Various test programs.
-
-    - doc
-      Various documentations and quickstart guide.
-
-    - extras
-      Contains extra data such as bash completion file.
-        Note: the presence of xmllint is required for bash-completion.
-         Python bindings for liblttng-ctl are also available there.
diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..daeb740
--- /dev/null
+++ b/README.md
@@ -0,0 +1,148 @@
+LTTng-tools
+===========
+
+LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
+tracing. The project includes the LTTng session daemon, consumer damon
+and relay daemon, as well as `liblttng-ctl`, a C library used to
+communicate with the session daemon, and `lttng`, a command line
+interface to `liblttng-ctl`.
+
+
+Requirements and optional dependencies
+--------------------------------------
+
+The following items are _required_ to build and run LTTng-tools
+components:
+
+  - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this
+    version is needed. However, `poll()` is also supported by
+    configuring LTTng-tools with the `--disable-epoll` option. Using
+    that, the kernel version may probably be older, but we can't provide
+    any guarantee. Please let us know if you are able to go lower
+    without any problems.
+  - **[`liburcu`](http://urcu.so/) >= 0.8.0**: userspace RCU library,
+    by Mathieu Desnoyers and Paul E. McKenney.
+  - **`libpopt` >= 1.13**:  command line arguments parsing library.
+    - Debian/Ubuntu package: `libpopt-dev`
+  - **`libuuid`**: universally unique ID library
+    - Debian/Ubuntu package: `uuid-dev`
+
+The following items are _optional_ dependencies:
+
+  - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
+    Enables the use of `lttng view` command.
+    - Debian/Ubuntu package: `babeltrace`
+  - **`libxml2` >= 2.7.6**:  XML document parsing library. Needed for
+    tracing session configuration saving/loading and machine interface
+    output support.
+    - Debian/Ubuntu package: `libxml2-dev`
+  - **Perl**: needed for `make check` and tests.
+  - **Python >= 3.0**: needed for `make check` and tests.
+    - Debian/Ubuntu package: `python3`
+  - **SWIG >= 2.0** and **Python 3 development headers**: needed for
+    Python bindings
+    (enabled at configure time with the `--enable-python-bindings` option).
+    - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
+  - **modprobe**: needed for automatic LTTng kernel modules loading
+    (kernel tracing).
+  - **bash**: needed for running `make check`.
+
+
+Building
+--------
+
+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
+  - Flex >= 2.5.35
+  - Bison >= 2.4
+
+If you use GNU gold, which is _not_ mandatory, make sure you have this
+version:
+
+  - GNU gold >= 2.22
+
+Before this version of GNU gold, we hit a
+[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
+Be advised that with GNU gold, you might have to specify
+`-L/usr/local/lib` in `LDFLAGS`.
+
+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-tools, do:
+
+    ./configure
+    make
+    sudo make install
+    sudo ldconfig
+
+If you want Python bindings, add the `--enable-python-bindings` option
+to `configure`. Please note that some distributions will need the
+following environment variables set before running configure:
+
+    export PYTHON="python3"
+    export PYTHON_CONFIG="/usr/bin/python3-config"
+
+
+Using
+-----
+
+Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
+with LTTng tracing. You can also use the `-h` or `--help` option of
+any `lttng` command, e.g.:
+
+    lttng enable-event --help
+
+A network streaming HOWTO can be found in
+[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
+helps you understand how to stream a LTTng 2.x trace.
+
+A Python binding HOWTO can be found in
+[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
+understand how to use the Python module to control LTTng.
+
+
+Contact
+-------
+
+Maintainer: [David Goulet](mailto:dgoulet@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-tools documentation.
+  - `include`: the public header files that will be installed on the system.
+  - `src/bin`: source code of LTTng-tools programs.
+    - `lttng-consumerd`: consumer daemon.
+    - `lttng-relayd`: relay daemon.
+    - `lttng-sessiond`: session daemon.
+    - `lttng`: command line interface for LTTng tracing control.
+  - `src/common`: common LTTng-tools source code.
+    - `compat`: compatibility library mostly for FreeBSD and Linux.
+    - `config`: tracing session configuration saving/loading.
+    - `hashtable`: library wrapper over Userspace RCU hashtables.
+    - `health`: health check subsytem.
+    - `index`: CTF index utilities.
+    - `kernel-consumer`: Linux kernel consumer.
+    - `kernel-ctl`: Linux kernel tracer control.
+    - `relayd`: relay daemon control.
+    - `sessiond-comm`: session daemon communication.
+    - `ust-consumer`: user space consumer.
+  - `src/lib`: source code of LTTng-tools libraries.
+    - `lttng-ctl`: LTTng control library.
+  - `tests`: various test programs.
index 50e155e85ec584adf5c19af2a4bbc2e32caed6df..018c27b2b939ef7cd075255fd01bcfd8b2b21b1e 100644 (file)
@@ -13,7 +13,7 @@ This is a quick start guide for the complete LTTng tool chain. This is divided
 in three sections respectively kernel tracing, user-space tracing and reading a
 trace.
 
-See the README file for installation procedure or use the various Linux
+See the README.md file for installation procedure or use the various Linux
 distribution packages.
 
 In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
index a89a2c80c747953c6b15e45f525d4b29891fb444..9ba6fea22657fa76e5d80cca6361db24e6c7d424 100644 (file)
@@ -5,7 +5,7 @@ STREAMING
 
 This is a brief howto for network streaming feature of lttng 2.0 toolchain.
 
-See the README file for installation procedure or use the various Linux
+See the README.md file for installation procedure or use the various Linux
 distribution packages.
 
 Terminology:
This page took 0.042248 seconds and 4 git commands to generate.