From a106a9f8513054954003122126a8b33b56de4bd8 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=A9mie=20Galarneau?= Date: Fri, 10 May 2013 11:24:23 -0400 Subject: [PATCH] Move "hello-static-lib" to doc/examples and add non-automake Makefiles MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit The examples are now automatically built as part of the default make target and plain Makefiles with no dependency on automake are provided for clarity. Update the manpage and README to reflect the change and remove lots of trailing whitespace. Signed-off-by: Jérémie Galarneau Signed-off-by: Mathieu Desnoyers --- .gitignore | 5 +- README | 17 +++-- configure.ac | 1 - doc/examples/Makefile.am | 15 +++++ doc/examples/README | 3 + doc/examples/demo/Makefile | 27 ++++++-- doc/examples/easy-ust/Makefile | 30 +++++++-- doc/examples/hello-static-lib/Makefile | 53 +++++++++++++++ .../examples}/hello-static-lib/README | 0 .../examples}/hello-static-lib/hello.c | 1 - {tests => doc/examples}/hello-static-lib/tp.c | 0 .../hello-static-lib/ust_tests_hello.h | 0 doc/man/lttng-ust.3 | 64 ++++++++++--------- tests/Makefile.am | 2 +- tests/demo/README | 5 -- tests/hello-static-lib/Makefile.am | 18 ------ 16 files changed, 166 insertions(+), 75 deletions(-) create mode 100644 doc/examples/README create mode 100644 doc/examples/hello-static-lib/Makefile rename {tests => doc/examples}/hello-static-lib/README (100%) rename {tests => doc/examples}/hello-static-lib/hello.c (99%) rename {tests => doc/examples}/hello-static-lib/tp.c (100%) rename {tests => doc/examples}/hello-static-lib/ust_tests_hello.h (100%) delete mode 100644 tests/demo/README delete mode 100644 tests/hello-static-lib/Makefile.am diff --git a/.gitignore b/.gitignore index 1065aa32..3d179401 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,10 @@ lttng-ust.pc ustctl/ustctl ust-consumerd/ust-consumerd +doc/examples/demo/demo +doc/examples/easy-ust/sample +doc/examples/hello-static-lib/hello + tests/hello/hello tests/hello.cxx/hello tests/same_line_tracepoint/same_line_tracepoint @@ -39,5 +43,4 @@ tests/ust-multi-test/ust-multi-test tests/trace_event/trace_event_test tests/tracepoint/benchmark/tracepoint_benchmark tests/tracepoint/tracepoint_test -tests/hello-static-lib/hello tests/snprintf/prog diff --git a/README b/README index dadcd1f5..4b3053c8 100644 --- a/README +++ b/README @@ -75,8 +75,11 @@ USAGE: library with "-llttng-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.* + - 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: @@ -94,14 +97,18 @@ USAGE: 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 + - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile - - Enable instrumentation and control tracing with the "lttng" command - from lttng-tools. See lttng-tools doc/quickstart.txt. - 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: although an application instrumented with + tracepoints can be compiled with g++, tracepoint probes should be + compiled with gcc (only tested with gcc so far). + ENVIRONMENT VARIABLES: diff --git a/configure.ac b/configure.ac index c70c142b..802ccaa5 100644 --- a/configure.ac +++ b/configure.ac @@ -266,7 +266,6 @@ AC_CONFIG_FILES([ tools/Makefile tests/Makefile tests/hello/Makefile - tests/hello-static-lib/Makefile tests/hello.cxx/Makefile tests/same_line_tracepoint/Makefile tests/snprintf/Makefile diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am index 2dc042a0..e9dd170d 100644 --- a/doc/examples/Makefile.am +++ b/doc/examples/Makefile.am @@ -1,6 +1,12 @@ +SUBDIRS = easy-ust demo hello-static-lib + +doc_examplesdir = ${docdir}/examples doc_examples_easy_ustdir = ${docdir}/examples/easy-ust doc_examples_gen_tpdir = ${docdir}/examples/gen-tp doc_examples_demodir = ${docdir}/examples/demo +doc_examples_hello_static_libdir = ${docdir}/examples/hello-static-lib + +dist_doc_examples_DATA = README dist_doc_examples_easy_ust_DATA = easy-ust/Makefile \ easy-ust/sample.c \ @@ -19,3 +25,12 @@ dist_doc_examples_demo_DATA = demo/demo.c \ demo/ust_tests_demo2.h \ demo/ust_tests_demo3.h \ demo/ust_tests_demo.h + +dist_doc_examples_hello_static_lib_DATA = hello-static-lib/Makefile \ + hello-static-lib/hello.c \ + hello-static-lib/README \ + hello-static-lib/ust_tests_hello.h \ + hello-static-lib/tp.c + +BUILD_EXAMPLES_FROM_TREE = 1 +export diff --git a/doc/examples/README b/doc/examples/README new file mode 100644 index 00000000..057311ea --- /dev/null +++ b/doc/examples/README @@ -0,0 +1,3 @@ +To build the examples from the source tree, the BUILD_EXAMPLES_FROM_TREE +environment variable must be defined. This will ensure the examples' +Makefiles use the source tree's public header files and binaries. diff --git a/doc/examples/demo/Makefile b/doc/examples/demo/Makefile index 41f43210..0c829da9 100644 --- a/doc/examples/demo/Makefile +++ b/doc/examples/demo/Makefile @@ -9,13 +9,30 @@ # granted, provided the above notices are retained, and a notice that # the code was modified is included with the above copyright notice. -# This Makefile is not using automake so that people may see how to build -# a program and tracepoint provider probes as stand-alone shared objects. +# This Makefile is not using automake so that users may see how to build +# a program with tracepoint provider probes as stand-alone shared objects. CC = gcc LIBS = -ldl # On Linux #LIBS = -lc # On BSD -CFLAGS = -I. +CFLAGS += -I. + +# Only necessary when building from the source tree and lttng-ust is not +# installed +ifdef BUILD_EXAMPLES_FROM_TREE +CFLAGS += -I../../../include/ +LIBLTTNG_UST_PATH = ../../../liblttng-ust/.libs/ +LDFLAGS += -L$(LIBLTTNG_UST_PATH) -Wl,-rpath='$$ORIGIN/$(LIBLTTNG_UST_PATH)' + +# Third-party Makefiles have to define these targets to integrate with an +# automake project +EMPTY_AUTOMAKE_TARGETS = distdir install install-data install-exec uninstall \ + install-dvi install-html install-info install-ps install-pdf \ + installdirs check installcheck mostlyclean distclean maintainer-clean \ + dvi html pdf ps info tags ctags +.PHONY: $(EMPTY_AUTOMAKE_TARGETS) +$(EMPTY_AUTOMAKE_TARGETS): +endif all: demo lttng-ust-provider-ust-tests-demo.so lttng-ust-provider-ust-tests-demo3.so @@ -23,13 +40,13 @@ lttng-ust-provider-ust-tests-demo.o: tp.c tp2.c ust_tests_demo.h ust_tests_demo2 $(CC) $(CFLAGS) -fpic -c -o $@ $< lttng-ust-provider-ust-tests-demo.so: lttng-ust-provider-ust-tests-demo.o - $(CC) -shared -o $@ -llttng-ust $< + $(CC) -shared -o $@ $(LDFLAGS) -llttng-ust $< lttng-ust-provider-ust-tests-demo3.o: tp3.c ust_tests_demo3.h $(CC) $(CFLAGS) -fpic -c -o $@ $< lttng-ust-provider-ust-tests-demo3.so: lttng-ust-provider-ust-tests-demo3.o - $(CC) -shared -o $@ -llttng-ust $< + $(CC) -shared -o $@ $(LDFLAGS) -llttng-ust $< demo.o: demo.c $(CC) $(CFLAGS) -c -o $@ $< diff --git a/doc/examples/easy-ust/Makefile b/doc/examples/easy-ust/Makefile index 1e3c9412..304632bb 100644 --- a/doc/examples/easy-ust/Makefile +++ b/doc/examples/easy-ust/Makefile @@ -10,20 +10,36 @@ # granted, provided the above notices are retained, and a notice that # the code was modified is included with the above copyright notice. -# This makefile is not using automake so that people can see how to make -# simply. It builds a program with a statically embedded tracepoint -# provider probe. +# This makefile is not using automake so that users can see how to build +# a program with a statically embedded tracepoint provider probe. # the "html" target helps for documentation (req. code2html) CC = gcc LIBS = -ldl -llttng-ust # On Linux #LIBS = -lc -llttng-ust # On BSD -CFLAGS = -I. +CFLAGS += -I. + +# Only necessary when building from the source tree and lttng-ust is not +# installed +ifdef BUILD_EXAMPLES_FROM_TREE +CFLAGS += -I../../../include/ +LIBLTTNG_UST_PATH = ../../../liblttng-ust/.libs/ +LDFLAGS += -L$(LIBLTTNG_UST_PATH) -Wl,-rpath='$$ORIGIN/$(LIBLTTNG_UST_PATH)' + +# Third-party Makefiles have to define these targets to integrate with an +# automake project +EMPTY_AUTOMAKE_TARGETS = distdir install install-data install-exec uninstall \ + install-dvi install-html install-info install-ps install-pdf \ + installdirs check installcheck mostlyclean distclean maintainer-clean \ + dvi pdf ps info tags ctags +.PHONY: $(EMPTY_AUTOMAKE_TARGETS) +$(EMPTY_AUTOMAKE_TARGETS): +endif all: sample sample: sample.o tp.o - $(CC) -o $@ $^ $(LIBS) + $(CC) -o $@ $^ $(LDFLAGS) $(LIBS) sample.o: sample.c sample_component_provider.h $(CC) $(CFLAGS) -c -o $@ $< @@ -33,7 +49,7 @@ tp.o: tp.c sample_component_provider.h html: sample_component_provider.html sample.html tp.html -%.html: %.c +%.html: %.c code2html -lc $< $@ %.html : %.h @@ -41,5 +57,5 @@ html: sample_component_provider.html sample.html tp.html .PHONY: clean clean: - rm -f *.html + rm -f *.html rm -f *.o sample diff --git a/doc/examples/hello-static-lib/Makefile b/doc/examples/hello-static-lib/Makefile new file mode 100644 index 00000000..81789e2b --- /dev/null +++ b/doc/examples/hello-static-lib/Makefile @@ -0,0 +1,53 @@ +# Copyright (C) 2013 Jérémie Galarneau +# +# THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED +# OR IMPLIED. ANY USE IS AT YOUR OWN RISK. +# +# Permission is hereby granted to use or copy this program for any +# purpose, provided the above notices are retained on all copies. +# Permission to modify the code and to distribute modified code is +# granted, provided the above notices are retained, and a notice that +# the code was modified is included with the above copyright notice. + +# This Makefile is not using automake so that users may see how to build +# a program with tracepoint provider probes compiled as static libraries. + +CC = gcc +CFLAGS += -I. +LIBS = -ldl -llttng-ust # On Linux +#LIBS = -lc -llttng-ust # On BSD + +# Only necessary when building from the source tree and lttng-ust is not +# installed +ifdef BUILD_EXAMPLES_FROM_TREE +CFLAGS += -I../../../include/ +LIBLTTNG_UST_PATH = ../../../liblttng-ust/.libs/ +LDFLAGS += -L$(LIBLTTNG_UST_PATH) -Wl,-rpath='$$ORIGIN/$(LIBLTTNG_UST_PATH)' + +# Third-party Makefiles have to define these targets to integrate with an +# automake project +EMPTY_AUTOMAKE_TARGETS = distdir install install-data install-exec uninstall \ + install-dvi install-html install-info install-ps install-pdf \ + installdirs check installcheck mostlyclean distclean maintainer-clean \ + dvi html pdf ps info tags ctags +.PHONY: $(EMPTY_AUTOMAKE_TARGETS) +$(EMPTY_AUTOMAKE_TARGETS): +endif + +all: hello + +lttng-ust-provider-hello.o: tp.c ust_tests_hello.h + $(CC) $(CFLAGS) -c -o $@ $< + +lttng-ust-provider-hello.a: lttng-ust-provider-hello.o + ar -rc $@ $< + +hello.o: hello.c + $(CC) $(CFLAGS) -c -o $@ $< + +hello: hello.o lttng-ust-provider-hello.a + $(CC) -o $@ $(LDFLAGS) $(LIBS) $^ + +.PHONY: clean +clean: + rm -f *.o *.a hello diff --git a/tests/hello-static-lib/README b/doc/examples/hello-static-lib/README similarity index 100% rename from tests/hello-static-lib/README rename to doc/examples/hello-static-lib/README diff --git a/tests/hello-static-lib/hello.c b/doc/examples/hello-static-lib/hello.c similarity index 99% rename from tests/hello-static-lib/hello.c rename to doc/examples/hello-static-lib/hello.c index 584d3f7b..693709d1 100644 --- a/tests/hello-static-lib/hello.c +++ b/doc/examples/hello-static-lib/hello.c @@ -88,7 +88,6 @@ int main(int argc, char **argv) netint = htonl(i); tracepoint(ust_tests_hello, tptest, i, netint, values, text, strlen(text), dbl, flt); - //usleep(100000); } fprintf(stderr, " done.\n"); return 0; diff --git a/tests/hello-static-lib/tp.c b/doc/examples/hello-static-lib/tp.c similarity index 100% rename from tests/hello-static-lib/tp.c rename to doc/examples/hello-static-lib/tp.c diff --git a/tests/hello-static-lib/ust_tests_hello.h b/doc/examples/hello-static-lib/ust_tests_hello.h similarity index 100% rename from tests/hello-static-lib/ust_tests_hello.h rename to doc/examples/hello-static-lib/ust_tests_hello.h diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 27b32e9f..aa52c590 100644 --- a/doc/man/lttng-ust.3 +++ b/doc/man/lttng-ust.3 @@ -40,11 +40,11 @@ focus on the various types that can be recorded into a trace event: TRACEPOINT_EVENT( /* * provider name, not a variable but a string starting with a - * letter and containing either letters, numbers or underscores. + * letter and containing either letters, numbers or underscores. * Needs to be the same as TRACEPOINT_PROVIDER. Needs to * follow the namespacing guide-lines in lttng/tracepoint.h: - * - * Must be included before include tracepoint provider + * + * Must be included before include tracepoint provider * ex.: project_event * ex.: project_component_event * @@ -59,19 +59,19 @@ TRACEPOINT_EVENT( /* * tracepoint name, same format as sample provider. Does not * need to be declared before. in this case the name is - * "message" + * "message" */ message, /* - * TP_ARGS macro contains the arguments passed for the tracepoint + * TP_ARGS macro contains the arguments passed for the tracepoint * it is in the following format * TP_ARGS(type1, name1, type2, name2, ... type10, name10) - * where there can be from zero to ten elements. - * typeN is the datatype, such as int, struct or double **. + * where there can be from zero to ten elements. + * typeN is the datatype, such as int, struct or double **. * name is the variable name (in "int myInt" the name would be - * myint) + * myint) * TP_ARGS() is valid to mean no arguments * TP_ARGS(void) is valid too */ @@ -80,7 +80,7 @@ TRACEPOINT_EVENT( double, doublearg, float, floatarg), /* - * TP_FIELDS describes how to write the fields of the trace event. + * TP_FIELDS describes how to write the fields of the trace event. * You can put expressions in the "argument expression" area, * typically using the input arguments from TP_ARGS. */ @@ -109,7 +109,7 @@ TRACEPOINT_EVENT( /* * ctf_array: a statically-sized array. * args: (type, field name, argument expression, value) - */ + */ ctf_array(long, arrfield1, values, 3) /* @@ -117,7 +117,7 @@ TRACEPOINT_EVENT( * a string. No need to be terminated by a null * character. * Behavior is undefined if "text" argument is NULL. - */ + */ ctf_array_text(char, arrfield2, text, 10) /* @@ -129,7 +129,7 @@ TRACEPOINT_EVENT( * be preferred to "char", since the signedness of * "char" is implementation-defined. * Behavior is undefined if "text" argument is NULL. - */ + */ ctf_sequence(char, seqfield1, text, size_t, textlen) @@ -176,54 +176,54 @@ declared before declaring a TRACEPOINT_LOGLEVEL. The loglevels go from 0 to 14. Higher numbers imply the most verbosity (higher event throughput expected. - + Loglevels 0 through 6, and loglevel 14, match syslog(3) loglevels semantic. Loglevels 7 through 13 offer more fine-grained selection of debug information. - + TRACE_EMERG 0 system is unusable - + TRACE_ALERT 1 action must be taken immediately - + TRACE_CRIT 2 critical conditions - + TRACE_ERR 3 error conditions - + TRACE_WARNING 4 warning conditions - + TRACE_NOTICE 5 normal, but significant, condition - + TRACE_INFO 6 informational message - + TRACE_DEBUG_SYSTEM 7 debug information with system-level scope (set of programs) - + TRACE_DEBUG_PROGRAM 8 debug information with program-level scope (set of processes) - + TRACE_DEBUG_PROCESS 9 debug information with process-level scope (set of modules) - + TRACE_DEBUG_MODULE 10 debug information with module (executable/library) scope (set of units) - + TRACE_DEBUG_UNIT 11 debug information with compilation unit scope (set of functions) - + TRACE_DEBUG_FUNCTION 12 debug information with function-level scope - + TRACE_DEBUG_LINE 13 debug information with line-level scope (TRACEPOINT_EVENT default) - + TRACE_DEBUG 14 debug-level message (trace_printf default) @@ -272,8 +272,10 @@ carefully: library with "\-llttng-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 + - 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: @@ -291,7 +293,7 @@ carefully: 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 + - 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 diff --git a/tests/Makefile.am b/tests/Makefile.am index 425440a5..317edcb0 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = . hello hello-static-lib same_line_tracepoint snprintf +SUBDIRS = . hello same_line_tracepoint snprintf if CXX_WORKS SUBDIRS += hello.cxx diff --git a/tests/demo/README b/tests/demo/README deleted file mode 100644 index 89e5889d..00000000 --- a/tests/demo/README +++ /dev/null @@ -1,5 +0,0 @@ -"demo" and "demo-trace" are moved to lttng-tools, under: - - tests/regression/ust/linking/ - -The "demo-trace" script was renamed to "demo_preload". diff --git a/tests/hello-static-lib/Makefile.am b/tests/hello-static-lib/Makefile.am deleted file mode 100644 index 699845b1..00000000 --- a/tests/hello-static-lib/Makefile.am +++ /dev/null @@ -1,18 +0,0 @@ -AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_builddir)/include -Wsystem-headers - -noinst_LTLIBRARIES = liblttng-ust-provider-ust-test-hello.la -liblttng_ust_provider_ust_test_hello_la_SOURCES = \ - tp.c ust_tests_hello.h -liblttng_ust_provider_ust_test_hello_la_LIBADD = \ - $(top_builddir)/liblttng-ust/liblttng-ust.la - -noinst_PROGRAMS = hello -hello_SOURCES = hello.c -hello_LDADD = liblttng-ust-provider-ust-test-hello.la - -if LTTNG_UST_BUILD_WITH_LIBDL -hello_LDADD += -ldl -endif -if LTTNG_UST_BUILD_WITH_LIBC_DL -hello_LDADD += -lc -endif -- 2.34.1