Merge master

CMakeLists.txt

@@ -1,6 +1,6 @@
 #
 # Caliper
-# 
+#
 
 project (caliper)
 cmake_minimum_required(VERSION 3.0)
@@ -42,19 +42,13 @@ endif()
 
 find_package(Threads)
 
-# Find OpenMP
-find_package(OpenMP)
-if (OpenMP_FLAG_DETECTED)
-  set(TEST_USE_OMP TRUE)
-endif()
-
 # Find OMPT header
 find_path(OMPT_INCLUDE_DIR ompt.h
   PATH_SUFFIXES include
   HINTS $ENV{OMPT_DIR} ${OMPT_DIR})
 
 if (OMPT_INCLUDE_DIR)
-  set(OMPT_FOUND TRUE)  
+  set(OMPT_FOUND TRUE)
   set(CALIPER_HAVE_OMPT TRUE)
   message(STATUS "OpenMP tools interface header ompt.h found in " ${OMPT_INCLUDE_DIR})
 else()
@@ -69,24 +63,25 @@ if (MPI_C_FOUND)
   set(CALIPER_HAVE_MPI TRUE)
 endif()
 
-# Find Mitos
-find_package(Mitos QUIET)
-if(Mitos_FOUND)
-  set(CALIPER_HAVE_MITOS TRUE)
-  list(APPEND CALIPER_EXTERNAL_LIBS mitos)
-  message(STATUS "Mitos sampling library found")
-endif()
-
 # Create a config header file
 configure_file(
   ${PROJECT_SOURCE_DIR}/caliper-config.h.in
   ${PROJECT_BINARY_DIR}/caliper-config.h)
 
+# Make caliper findable
+configure_file(
+  ${PROJECT_SOURCE_DIR}/caliper-config.cmake.in
+  ${PROJECT_BINARY_DIR}/caliper-config.cmake
+  @ONLY)
+install(FILES ${PROJECT_BINARY_DIR}/caliper-config.cmake DESTINATION share/cmake/caliper)
+install(EXPORT caliper                                   DESTINATION share/cmake/caliper)
+
+
 install(FILES ${PROJECT_BINARY_DIR}/caliper-config.h DESTINATION include)
 
 add_subdirectory(doc)
 add_subdirectory(src)
 add_subdirectory(test)
 
 # Install exports
-install(EXPORT caliper DESTINATION lib/cmake)
+#install(EXPORT caliper DESTINATION lib/cmake)

LICENSE

@@ -1,10 +1,13 @@
 Copyright (c) 2015, Lawrence Livermore National Security, LLC.  
 Produced at the Lawrence Livermore National Laboratory.
 
-This file is part of Caliper.
 Written by David Boehme, [email protected].
+LLNL-CODE-678900
 All rights reserved.  
 
+This file is part of Caliper.
+For details, see https://github.com/scalability-llnl/Caliper.
+
 Redistribution and use in source and binary forms, with or without modification, are
 permitted provided that the following conditions are met:
 

README.md

@@ -1,12 +1,14 @@
 Caliper: Context Annotation Library (for Performance)
 ==========================================
 
-by David Boehme, [email protected]
-
 Caliper is a generic context annotation system. It gives programmers
 the ability to provide arbitrary program context information to 
 (performance) tools at runtime.
 
+Released under a BSD license, `LLNL-CODE-678900`. 
+See `LICENSE` file for details.
+
+
 Documentation
 ------------------------------------------
 
@@ -82,26 +84,28 @@ int main(int argc, char* argv[])
     phase_ann.end();                           // Context is "phase=main"
 
     if (count > 0) {
-        cali::Annotation::AutoScope 
-            loop_s( phase_ann.begin("loop") ); // Context is "phase=main/loop"
+        cali::Annotation::Guard 
+            g_loop( phase_ann.begin("loop") ); // Context is "phase=main/loop"
         
         cali::Annotation 
             iteration_ann("iteration", CALI_ATTR_ASVALUE);
+        cali::Annotation::Guard
+            g_iteration( iteration_ann );
         
         for (int i = 0; i < count; ++i) {
             iteration_ann.set(i);              // Context is "phase=main/loop,iteration=i"
         }
-
-        iteration_ann.end();                   // Context is "phase=main/loop"
     }                                          // Context is "phase=main"
 
     phase_ann.end();                           // Context is ""
 }
 ```
 
-A `cali::Annotation` object creates and stores an annotation attribute. 
-An annotation attribute should have a unique name. 
-The example above creates two annotation attributes, "phase" and "iteration".
+The `cali::Annotation` class is the primary source-code instrumentation 
+interface for Caliper. Annotation objects provide access to named Caliper 
+context attributes. If a referenced attribute does not exist yet, it will
+be created automatically. The example above creates two context attributes, 
+"phase" and "iteration".
 
 The _Caliper context_ is the set of all active attribute/value pairs.
 Use the `begin()`, `end()` and `set()` methods of an annotation object
@@ -110,19 +114,23 @@ methods are overloaded for common data types (strings, integers, and
 floating point).
 
 * `cali::Annotation::begin(value)` puts `value` into the context for
-the given annotation attribute.  The value is appended to the current
-values of the attribute, which allows you to create hierarchies (as in
+the given context attribute. The value is appended to the current
+values of the attribute to enable the creation of hierarchies. (as in
 the "phase" annotation in the example).
 
-* `cali::Annotation::set(value)` sets the value of the annotation
-attribute to `value`.  It overwrites the current value of the
-annotation attribute on the same hierarchy level.
+* `cali::Annotation::set(value)` sets the value of the referenced context
+attribute to `value`.  In contrast to `begin()`, it overwrites the current 
+value of the context attribute.
 
-* `cali::Annotation::end()` removes the innermost value of the given
-  annotation attribute from the context. It is the user's
+* `cali::Annotation::end()` removes the innermost value of the referenced
+  context attribute from the context. It is the user's
   responsibility to nest `begin()`/`set()` and `end()` calls
   correctly.
 
+* A `cali::Annotation::Guard` object automatically invokes the `end()` 
+  method of the referenced Annotation object when the surrounding C++ 
+  scope is left.
+
 ### Build and link annotated programs
 
 To build a program with Caliper annotations, link it with the Caliper

caliper-config.cmake.in

@@ -0,0 +1,47 @@
+# - caliper: (David's TO DO)
+#
+#=============================================================================
+# caliper is ....  (David's TO DO)
+#
+#=== Usage ===================================================================
+# This file allows caliper to be automatically detected by other libraries
+# using CMake.  To build with caliper, you can do one of two things:
+#
+#   1. Set the caliper_DIR environment variable to the root of the Caliper
+#      installation.  If you loaded caliper through a dotkit, this may already
+#      be set, and caliper will be autodetected by CMake.
+#
+#   2. Configure your proeject with this option:
+#      -D caliper_DIR=/path/to/dir/containing/this/file
+#
+# If you have done either of these things, then CMake should automatically find
+# and include this file when you call find_package(caliper) from your
+# CMakeLists.txt file.
+#
+#=== Components ==============================================================
+# (David's TO DO)
+#
+# To link against these, just do, for example:
+#
+#   find_package(caliper REQUIRED)
+#   add_executable(foo foo.c)
+#   target_link_libraries(foo caliper-component)
+#
+# That's all!
+#
+if (NOT caliper_CONFIG_LOADED)
+  set(caliper_CONFIG_LOADED TRUE)
+
+  # Install layout
+  set(caliper_INSTALL_PREFIX @CMAKE_INSTALL_PREFIX@)
+  set(caliper_INCLUDE_DIR    ${caliper_INSTALL_PREFIX}/include)
+  set(caliper_LIB_DIR        ${caliper_INSTALL_PREFIX}/lib)
+  set(caliper_CMAKE_DIR      ${caliper_INSTALL_PREFIX}/share/cmake/caliper)
+
+  # Includes needed to use caliper
+  set(caliper_INCLUDE_PATH ${caliper_INCLUDE_DIR})
+  set(caliper_LIB_PATH     ${caliper_LIB_DIR})
+
+  # Library targets imported from file
+  include(${caliper_CMAKE_DIR}/caliper.cmake)
+endif()

caliper-config.h.in

@@ -2,7 +2,6 @@
 #define CALIPER_CONFIG_H
 
 #cmakedefine CALIPER_HAVE_OMPT 
-#cmakedefine CALIPER_HAVE_MITOS 
 #cmakedefine CALIPER_HAVE_MPI
 #cmakedefine CALIPER_HAVE_LIBUNWIND
 #cmakedefine CALIPER_HAVE_PAPI

doc/api.rst

@@ -0,0 +1,54 @@
+Annotation API
+================================
+
+Caliper provides source-code instrumentation APIs for C and C++ to
+create and access Caliper context attributes. 
+
+C++ annotation API
+--------------------------------
+
+The `cali::Annotation` class provides the C++ instrumentation interface.
+
+.. cpp:class:: cali::Annotation
+
+   #include <Annotation.h>
+
+   Instrumentation interface to add and manipulate context attributes
+
+   The Annotation class is the primary source-code instrumentation interface
+   for Caliper. Annotation objects provide access to named Caliper context 
+   attributes. If the referenced attribute does not exist yet, it will be 
+   created automatically.
+
+   Example:
+
+   .. code-block:: c++
+
+     cali::Annotation phase_ann("myprogram.phase");
+
+     phase_ann.begin("Initialization");
+       // ...
+     phase_ann.end();
+
+   This example creates an annotation object for the `myprogram.phase`
+   attribute, and uses the `begin()` and `end()` methods to mark a section 
+   of code where that attribute is set to "Initialization".
+
+   Note that the access to a named context attribute through Annotation 
+   objects is not exclusive: two different Annotation objects can reference and
+   update the same context attribute.
+
+   The Annotation class is *not* threadsafe; however, threads can safely
+   access the same context attribute simultaneously through different 
+   Annotation objects.
+
+   .. cpp:function:: cali::Annotation::Annotation(const char* name, \
+        int properties = 0)
+
+      Constructor. Constructs an annotation object to manipulate the Caliper 
+      context attribute `name`. If the attribute does not already exist,
+      it will be created with the attribute properties specified in
+      `properties`. See `cali_attr_properties` for a list of attribute
+      properties.
+
+

doc/build.rst

@@ -15,6 +15,26 @@ Compiler. Unpack the source distribution and proceed as follows:
      $ make 
      $ make install
 
+Building on BG/Q
+--------------------------------
+
+When building on a BlueGene/Q system, the libraries must be cross-compiled to
+work correctly on the compute nodes. Use the provided toolchain file to build
+with clang, like so:
+
+.. code-block:: sh
+
+     $ cd <path to caliper root directory>
+     $ mkdir build && cd build
+     $ cmake -DCMAKE_INSTALL_PREFIX=<path to install location> \ 
+         -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/bgq-dynamic.toolchain \
+         -DCMAKE_CXX_FLAGS=-stdlib=libc++ \
+         ..
+     $ make 
+     $ make install
+
+When processing the created cali files, make sure to use a version of
+`cali-query` complied for the frontend node. 
 
 Optional modules
 --------------------------------

doc/index.rst

@@ -22,7 +22,7 @@ Contents:
    usage
    configuration
    services
-
+   api
 
 Indices and tables
 ==================

doc/services.rst

@@ -54,6 +54,18 @@ CALI_CALLPATH_SKIP_FRAMES=<number of frames>
   Skip a number of stack frames. This avoids recording stack frames
   within the Caliper library. Default: 10
 
+Environment Information
+--------------------------------
+
+The environment information (`env`) service collects runtime environment 
+information at process startup and adds it to the Caliper context.
+
+Specifically, it collects
+
+ * The process' command line (program name and arguments)
+ * Machine type and hostname, and operating system type, release, and version
+ * Date and time of program start in text form
+
 Event
 --------------------------------