Add 'ppaml_tracer_init_from_env'

This new API function is similar to 'ppaml_tracer_init', but instead of
accepting the report base name as an argument, it pulls it from the
'PPAMLTRACER_TRACE_BASE' environment variable.  This is useful for users
who want to be able to vary the locations of trace reports but do not
want to build tracing into their configuration file / command-line
argument parsers.

4 files changed, 101 insertions, 2 deletions

diff --git a/configure.ac b/configure.ac
index 3e3a1d8..3933d8b 100644
--- a/configure.ac
+++ b/configure.ac
@@ -74,7 +74,7 @@ AC_CHECK_TYPES(
 	[],
 	[[#define _POSIX_C_SOURCE 199309L
 #include <time.h>]])
-AC_CHECK_FUNCS([mkdtemp nanosleep nftw])
+AC_CHECK_FUNCS([mkdtemp nanosleep nftw setenv unsetenv])
 PKG_CHECK_MODULES([check], [check >= 0.9.4],
 	[],
 	[AC_MSG_WARN([check not found; `make check' will fail])])
diff --git a/include/ppaml/tracer.h b/include/ppaml/tracer.h
index df9891a..b093cc8 100644
--- a/include/ppaml/tracer.h
+++ b/include/ppaml/tracer.h
@@ -65,6 +65,31 @@
 int ppaml_tracer_init(ppaml_tracer_t *tracer, const char report_name_base[]);
 
 /**
+ * Initializes a ppaml_tracer_t, taking settings from environment variables.
+ *
+ * @relates ppaml_tracer_t
+ *
+ * The trace report will be stored in Open Trace Format; all trace file paths
+ * will begin with the value in the environment variable @c
+ * PPAMLTRACER_TRACE_BASE.
+ *
+ * @param[out] tracer pointer to the tracer to be initialized
+ *
+ * @pre @p tracer is nonnull.
+ * @pre @p *tracer is uninitialized.
+ *
+ * @return 0 upon success
+ * @return 1 if the Open Trace Format file manager could not be initialized
+ * @return 2 if the Open Trace Format writer could not be initialized
+ * @return 3 if setting the trace resolution failed
+ * @return 4 if defining the main OTF process failed
+ * @return 5 if @c PPAMLTRACER_TRACE_BASE is unset or empty
+ *
+ * @post If the function return successfully, @p *tracer is initialized.
+ */
+int ppaml_tracer_init_from_env(ppaml_tracer_t *tracer);
+
+/**
  * Finalizes a ppaml_tracer_t.
  *
  * @relates ppaml_tracer_t
diff --git a/src/tracer.c b/src/tracer.c
index be2f3cc..3b39759 100644
--- a/src/tracer.c
+++ b/src/tracer.c
@@ -24,6 +24,7 @@
 
 #include <stdint.h>
 #include <stdlib.h>
+#include <string.h>
 
 #include <otf.h>
 
@@ -59,6 +60,23 @@ int ppaml_tracer_init(
 done:	return r;
 }
 
+int ppaml_tracer_init_from_env(ppaml_tracer_t *const tracer)
+{
+	int r = 0;
+	// Figure out where to put the trace.
+	const char *const report_name_base = getenv("PPAMLTRACER_TRACE_BASE");
+	require_nonnull(report_name_base, 5);
+	if (report_name_base[0] == '\0') {
+		/* The variable exists, but it's empty, so we can't do anything
+		 * with it. */
+		r = 5;
+		goto done;
+	}
+	// Create the trace.
+	r = ppaml_tracer_init(tracer, report_name_base);
+done:	return r;
+}
+
 int ppaml_tracer_done(ppaml_tracer_t *const tracer)
 {
 	int r = 0;
diff --git a/test/check_ppamltracer.c b/test/check_ppamltracer.c
index 73a4631..e842789 100644
--- a/test/check_ppamltracer.c
+++ b/test/check_ppamltracer.c
@@ -22,7 +22,7 @@
 #	include <config.h>
 #endif
 
-#define _POSIX_C_SOURCE 199309L
+#define _POSIX_C_SOURCE 200112L
 
 #include <stdint.h>
 #include <stdlib.h>
@@ -58,6 +58,49 @@
 	END_TEST
 #endif
 
+#if (HAVE_FIXTURE_tmpdir && HAVE_UNISTD_H && HAVE_SETENV)
+#	define HAVE_TEST_init_from_env
+	START_TEST(test_init_from_env)
+	{
+		// Figure out where to put the trace.
+		char trace_base[128];
+		strcpy(trace_base, tmpdir_name());
+		strcat(trace_base, "/trace");
+		// Tell ppamltracer where.
+		ck_assert(
+			setenv("PPAMLTRACER_TRACE_BASE", trace_base, 1) == 0);
+		// Create the trace.
+		ppaml_tracer_t tracer;
+		ck_assert(
+			ppaml_tracer_init_from_env(&tracer) == 0);
+		ck_assert(ppaml_tracer_done(&tracer) == 0);
+		// Make sure it's in the right place.
+		strcat(trace_base, ".otf");
+		ck_assert(access(trace_base, F_OK) == 0);
+	}
+	END_TEST
+
+#	define HAVE_TEST_init_from_env_fails_on_empty
+	START_TEST(test_init_from_env_fails_on_empty)
+	{
+		ck_assert(setenv("PPAMLTRACER_TRACE_BASE", "", 1) == 0);
+		ppaml_tracer_t tracer;
+		ck_assert(ppaml_tracer_init_from_env(&tracer) == 5);
+	}
+	END_TEST
+#endif
+
+#if (HAVE_FIXTURE_tmpdir && HAVE_UNISTD_H && HAVE_UNSETENV)
+#	define HAVE_TEST_init_from_env_fails_on_unset
+	START_TEST(test_init_from_env_fails_on_unset)
+	{
+		ck_assert(unsetenv("PPAMLTRACER_TRACE_BASE") == 0);
+		ppaml_tracer_t tracer;
+		ck_assert(ppaml_tracer_init_from_env(&tracer) == 5);
+	}
+	END_TEST
+#endif
+
 #if (HAVE_FIXTURE_tmpdir && HAVE_FIXTURE_trace_valid)
 #	define HAVE_TEST_simple_creates_valid_trace
 	START_TEST(test_simple_creates_valid_trace)
@@ -198,6 +241,19 @@ Suite *ppamltracer_suite()
 		tcase_add_test(tc, test_init_creates_trace);
 #	endif
 	suite_add_tcase(s, tc);
+	// Test case: init from env
+	tc = tcase_create("init_from_env");
+	tmpdir_add_checked(tc);
+#	ifdef HAVE_TEST_init_from_env
+		tcase_add_test(tc, test_init_from_env);
+#	endif
+#	ifdef HAVE_TEST_init_from_env_fails_on_unset
+		tcase_add_test(tc, test_init_from_env_fails_on_unset);
+#	endif
+#	ifdef HAVE_TEST_init_from_env_fails_on_empty
+		tcase_add_test(tc, test_init_from_env_fails_on_empty);
+#	endif
+	suite_add_tcase(s, tc);
 	// Test case: valid
 	tc = tcase_create("valid");
 	tmpdir_add_checked(tc);