From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Wed, 9 Jun 2021 19:39:25 +0000 (-0400)
Subject: doc/man: only mention `-llttng-ust-common` in synopses (conditionally)
X-Git-Url: https://git.lttng.org/?p=lttng-ust.git;a=commitdiff_plain;h=e9f549af207b2228357442e1fafa109bd459e6f3

doc/man: only mention `-llttng-ust-common` in synopses (conditionally)

LTTng-UST only requires that you link your application or tracepoint
provider package with `-llttng-ust-common` if you define
`_LGPL_SOURCE` before you include, directly or indirectly,
`<lttng/tracepoint.h>`.

The `_LGPL_SOURCE` definition is specific to the EfficiOS/LTTng
projects.

Because defining `_LGPL_SOURCE` is not considered the typical scenario,
remove instructions to link with `-llttng-ust-common` throughout the
manual pages, except in synopses, to make such instructions more
readable/light.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Change-Id: I460a2f746d5e2904660a11b3151d0d01776361db
---

diff --git a/doc/man/lttng-ust.3.txt b/doc/man/lttng-ust.3.txt
index 55b2b20d..11fe7684 100644
--- a/doc/man/lttng-ust.3.txt
+++ b/doc/man/lttng-ust.3.txt
@@ -81,7 +81,11 @@ SYNOPSIS
 #define *lttng_ust_tracepoint*('prov_name', 't_name', ...)
 #define *lttng_ust_tracepoint_enabled*('prov_name', 't_name')
 
-Link with `-llttng-ust -llttng-ust-common -ldl`, following this man page.
+Link with, following this manual page:
+
+* `-llttng-ust -ldl`
+* If you define `_LGPL_SOURCE` before including
+  `<lttng/tracepoint.h>` (directly or indirectly): `-llttng-ust-common`
 
 
 DESCRIPTION
@@ -728,12 +732,12 @@ change, but need not to be otherwise recompiled (unless the tracepoint
 provider's API changes).
 
 Then, link your application with this object file (or with the static
-library containing it) and with `liblttng-ust`, `liblttng-ust-common`,
-and `libdl` (`libc` on a BSD system):
+library containing it) and with `liblttng-ust` and `libdl` (`libc` on a
+BSD system):
 
 [role="term"]
 ----
-$ cc -o app tp.o app.o -llttng-ust -llttng-ust-common -ldl
+$ cc -o app tp.o app.o -llttng-ust -ldl
 ----
 
 
@@ -783,8 +787,7 @@ It is then linked as a shared library like this:
 
 [role="term"]
 ----
-$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust \
-     -llttng-ust-common
+$ cc -shared -Wl,--no-as-needed -o tp.so tp.o -llttng-ust
 ----
 
 This tracepoint provider shared object isn't linked with the user
@@ -1218,7 +1221,7 @@ like this:
 ----
 $ cc -c -I. tp.c
 $ cc -c app.c
-$ cc -o app tp.o app.o -llttng-ust -llttng-ust-common -ldl
+$ cc -o app tp.o app.o -llttng-ust -ldl
 ----
 
 Using the man:lttng(1) tool, create an LTTng tracing session, enable
diff --git a/doc/man/lttng_ust_tracef.3.txt b/doc/man/lttng_ust_tracef.3.txt
index 0c901720..e103c12a 100644
--- a/doc/man/lttng_ust_tracef.3.txt
+++ b/doc/man/lttng_ust_tracef.3.txt
@@ -17,7 +17,11 @@ SYNOPSIS
 #define *lttng_ust_tracef*('fmt', ...)
 #define *lttng_ust_vtracef*('fmt', 'ap')
 
-Link with `-llttng-ust -llttng-ust-common`.
+Link with:
+
+* `-llttng-ust`
+* If you define `_LGPL_SOURCE` before including
+  `<lttng/tracef.h>` (directly or indirectly): `-llttng-ust-common`
 
 
 DESCRIPTION
diff --git a/doc/man/lttng_ust_tracelog.3.txt b/doc/man/lttng_ust_tracelog.3.txt
index d0a315d1..760ac8a4 100644
--- a/doc/man/lttng_ust_tracelog.3.txt
+++ b/doc/man/lttng_ust_tracelog.3.txt
@@ -17,8 +17,11 @@ SYNOPSIS
 #define *lttng_ust_tracelog*('level', 'fmt', ...)
 #define *lttng_ust_vtracelog*('level', 'fmt', 'ap')
 
-Link with `-llttng-ust -llttng-ust-common`.
+Link with:
 
+* `-llttng-ust`
+* If you define `_LGPL_SOURCE` before including
+  `<lttng/tracelog.h>` (directly or indirectly): `-llttng-ust-common`
 
 DESCRIPTION
 -----------