Merge remote-tracking branch 'origin/master' into nbrei_gluex_port

README.md

@@ -12,7 +12,7 @@ check it out and give feedback to help us improve it.
 Just to whet your appetite a little, the code snippet below is the most common signature of JANA. A large fraction of end users won't really need to know much more than this.
 
 ```
-auto tracks = jevent->Get<DTrack>(tracks);
+auto tracks = jevent->Get<DTrack>();
 
 for(auto t : tracks){
   // ... do something with a track
@@ -29,4 +29,4 @@ cmake --build build -j 10 --target install
 install/bin/jana -Pplugins=JTest
 ```
 
-For detailed instructions, see the [howto guide](https://jeffersonlab.github.io/JANA2/Installation.html).
+For detailed instructions, see the [howto guide](https://jeffersonlab.github.io/JANA2/Installation.html).

cmake/FindZeroMQ.cmake

@@ -4,16 +4,31 @@
 # ZeroMQ_INCLUDE_DIRS - The ZeroMQ include directories
 # ZeroMQ_LIBRARIES - The libraries needed to use ZeroMQ
 # ZeroMQ_DEFINITIONS - Compiler switches required for using ZeroMQ
+
 find_path (ZeroMQ_INCLUDE_DIR zmq.h)
 find_library (ZeroMQ_LIBRARY NAMES zmq)
 set (ZeroMQ_LIBRARIES ${ZeroMQ_LIBRARY})
 set (ZeroMQ_INCLUDE_DIRS ${ZeroMQ_INCLUDE_DIR})
-include (FindPackageHandleStandardArgs)
+
+# Use parent directory name of the include directory to
+# indicate where we are getting this from. This is
+# informational only for when the top-level file
+# prints "USE_ZEROMQ  On  -->"
+# n.b. it is possible the library and include directories
+# don't point to the same version!
+get_filename_component(ZeroMQ_DIR ${ZeroMQ_INCLUDE_DIR} DIRECTORY)
+
+# For debugging
+#message(STATUS "ZeroMQ_INCLUDE_DIR=${ZeroMQ_INCLUDE_DIR}")
+#message(STATUS "ZeroMQ_LIBRARY=${ZeroMQ_LIBRARY}")
+#message(STATUS "ZeroMQ_DIR=${ZeroMQ_DIR}")
+
 # handle the QUIETLY and REQUIRED arguments and set ZeroMQ_FOUND to TRUE
 # if all listed variables are TRUE
 
+include (FindPackageHandleStandardArgs)
 find_package_handle_standard_args(ZeroMQ
         FOUND_VAR ZeroMQ_FOUND
         VERSION_VAR ZeroMQ_VERSION
-        REQUIRED_VARS ZeroMQ_DIR ZeroMQ_INCLUDE_DIR ZeroMQ_LIBRARY
+        REQUIRED_VARS ZeroMQ_DIR ZeroMQ_INCLUDE_DIRS ZeroMQ_LIBRARIES
         )

docs/GUI_Monitor_Debug.md

@@ -31,14 +31,22 @@ running on either the local node or a remote node. For this to work, the followi
    This should generally be added to the *end* of the plugin list
    like this:
 
-      ```jana -Pplugins=JTest,janacontrol```
+```
+jana -Pplugins=JTest,janacontrol
+```
+
+To start the JANA control GUI, just run the `jana-control.py` program:
+
+```
+jana-control.py
+```
 
 By default, it will try to attach to port 11238 on the localhost. It
 does not matter whether the JANA process is already running or not.
 It will automatically connect when it starts and reconnect if the process
 is restarted.
 
-The following command line options are available:
+The following command line options are available for `jana-control.py`:
 
 <pre>
 -h, --help     Print this Usage statement and exit
@@ -48,10 +56,24 @@ The following command line options are available:
 
 n.b. To set the port used by the remote JANA process set the
 jana:zmq_port configuration parameter when that process is started.
+For example:
+
+```
+jana -Pplugins=JTest,janacontrol -Pjana:zmq_port=12345
+```
 
 Debugger
 --------------
 
+The `Debugger` GUI here is really just a browser. It does not allow 
+for true control flow debugging. For that, please look at the command line
+debugger features of JANA2. This is intended to give a way to step
+through events and examine the exposed data members of the objects
+created in the event.
+
+To open the Debugger window, just press the button in the lower
+right hand coner of the control window.
+
 ![](images/JANA_Debugger_GUI.png)
 
 The GUI can be used to step through events in the JANA process and
@@ -69,7 +91,9 @@ events can be examined and stepped through. To stall processing on the
 very first event, the JANA process should have the jana:debug_mode
 config. parameter set to a non-zero value when it is started. e.g.
 
-``jana -Pplugins=myplugin1,myplugin2,janacontrol -Pjana:debug_mode=1 file1.dat``
+```
+jana -Pplugins=JTest,janacontrol -Pjana:debug_mode=1
+```
 
 Once an event is loaded, click on a factory to display a list of 
 objects it created for this event (displayed as the object's hexadecimal

docs/Installation.md

@@ -16,11 +16,10 @@ title: JANA: Multi-threaded HENP Event Reconstruction
 ### Building JANA
 
 First, set your `$JANA_HOME` environment variable. This is where the executables, libraries, headers, and plugins
-get installed. You will need to tell CMake to install to `$JANA_HOME` manually -- this is on purpose to avoid accidentally
-clobbering an existing JANA installation. Luckily, all you have to do is pass `-DCMAKE_INSTALL_PREFIX=$JANA_HOME`
-to CMake. Be aware that if you change $JANA_HOME, you'll need to rerun cmake, and sometimes you'll also need to invalidate your CMake cache. 
-Also be aware that although CMake usually defaults `CMAKE_INSTALL_PREFIX` to `/usr/local`, we have disabled this because 
-we rarely want this in practice, and we don't want the build system picking up outdated headers and libraries we installed to `/usr/local` by accident. 
+get installed. (It is also where we will clone the source). CMake will install to `$JANA_HOME` if it is set (it
+will install to `${CMAKE_BINARY_DIR}/install` if not). Be aware that although CMake usually defaults
+`CMAKE_INSTALL_PREFIX` to `/usr/local`, we have disabled this because we rarely want this in practice, and we
+don't want the build system picking up outdated headers and libraries we installed to `/usr/local` by accident.
 If you want to set `JANA_HOME=/usr/local`, you are free to do so, but you must do so deliberately.
 
 Next, set your build directory. This is where CMake's caches, logs, intermediate build artifacts, etc go. The convention
@@ -30,16 +29,18 @@ a `cmake-build-debug` directory which works just fine.
 Finally, you can cd into your build directory and build and install everything the usual CMake way.
 
 ~~~ bash
-git clone https://github.com/JeffersonLab/JANA2   # Get JANA
-export JANA_HOME=~/jana_home                      # Set install dir
-export PATH=$PATH:$JANA_HOME/bin                  # Put jana executable on path
+export JANA_VERSION=v2.0.5                    # Convenient to set this once for specific release
+export JANA_HOME=${PWD}/JANA${JANA_VERSION}   # Set full path to install dir
 
-mkdir build                                       # Set build dir
+git clone https://github.com/JeffersonLab/JANA2 --branch ${JANA_VERSION} ${JANA_HOME}  # Get JANA2
+
+mkdir build                                   # Set build dir
 cd build
-cmake ../JANA2 -DCMAKE_INSTALL_PREFIX=$JANA_HOME  # Generate makefiles
-make -j8 install                                  # Build (using 8 threads) and install
-jana -Pplugins=JTest                              # Run JTest plugin to verify successful install
+cmake3 ${JANA_HOME}  # Generate makefiles     # Generate makefiles
+make -j8 install                              # Build (using 8 threads) and install
 
+source ${JANA_HOME}/bin/jana-this.sh          # Set PATH (and other envars)
+jana -Pplugins=JTest                          # Run JTest plugin to verify successful install
 ~~~
 
 Note: If you want to use a compiler other than the default one on your system, it is not enough to modify your

docs/Tutorial.md

@@ -29,7 +29,7 @@ The installation process is described [here](Installation.html). We can quickly
 was successful by running a builtin benchmarking/scaling test:
 
 ```
-jana -Pplugins=JTest -b
+jana -Pplugins=JTest -b   # (cancel with Ctrl-C)
 ```
 
 We can understand this command as follows:
@@ -52,61 +52,44 @@ measuring the overall throughput. You can cancel processing at any time by press
 With JANA working, we can now create our own plugin. JANA provides a script which generates code skeletons 
 to help us get started. We shall generate a skeleton for a plugin named "QuickTutorial" as follows:
 ```
-cd ~
-jana-generate.py StandalonePlugin QuickTutorial
+jana-generate.py Plugin QuickTutorial
 ```
 
-This creates the following directory tree. Examine the files `QuickTutorial.cc`, which provides the plugin
- entry point, and `QuickTutorialProcessor.cc`, which is where the majority of the work happens. The generated
- files include lots of comments providing helpful hints on their use. 
+This creates the following directory tree. By default, a minimal skelton is created in a single file:
+`QuickTutorial.cc`. This provides a JEventProcessor class as well as the the plugin entry point. The
+generated files include lots of comments providing helpful hints on their use. 
 
 ```
 QuickTutorial/
 ├── CMakeLists.txt
-├── cmake
-│   └── FindJANA.cmake
-├── src
-│   ├── CMakeLists.txt
-│   ├── QuickTutorial.cc
-│   ├── QuickTutorialProcessor.cc
-│   └── QuickTutorialProcessor.h
-└── tests
-    ├── catch.hpp
-    ├── CMakeLists.txt
-    ├── IntegrationTests.cc
-    └── TestsMain.cc
+│├─ QuickTutorial.cc
 ```
 
-## Integrating into an existing project
-
-If we are working with an existing project such as eJANA or GlueX, we don't need the CMake
-project definition, CMake helper files, or tests boilerplate. All we need is the inner `src`
-directory, which we copy into its own leaf in the project tree:
-```
-cp QuickTutorial/src $PATH_TO_PROJECT_SOURCE/src/plugins/QuickTutorial
-```
+The `jana-generate.py Plugin ...` command provides some option flags as well that can be given at the 
+end of the command line. Run `jana-generate.py --help` to see what they are.
 
-For convenience, `jana-generate.py` will generate the stripped-down plugin directly if we specify 
-`ProjectPlugin` instead. 
+## Integrating into an existing project
 
+If you are working with an existing project such as eJANA or GlueX, then you don't need the CMake
+project. All you need are the source files (e.g. `QuickTutorial.cc`):
 ```
-cd $PATH_TO_PROJECT_SOURCE/src/plugins
-jana-generate.py ProjectPlugin QuickTutorial
+cp QuickTutorial $PATH_TO_PROJECT_SOURCE/src/plugins/QuickTutorial
 ```
 
-Either way, we'll have to manually tell the parent CMakeLists.txt to 
+Be aware that you will have to manually tell the parent CMakeLists.txt to 
 `add_subdirectory(QuickTutorial)`.
 
-The rest of the tutorial assumes that we are using a standalone plugin instead.
+The rest of the tutorial assumes that we are using a standalone plugin.
 
 
 ## Building the plugin
 We build and run the plugin with the following:
 
 ```
+cd QuickTutorial
 mkdir build
 cd build
-cmake ..
+cmake3 ..
 make install
 jana -Pplugins=QuickTutorial
 ```
@@ -121,37 +104,46 @@ assume that we don't have access to an event source, so we'll create one ourselv
 source will emit an infinite stream of random data, so we'll name it RandomSource.
 
 ```
-cd src
+cd ..
 jana-generate.py JEventSource RandomSource
 ```
 
 This creates two files, `RandomSource.cc` and `RandomSource.h`, in the current directory. We'll
 need to add them to `CMakeLists.txt` ourselves. Note that we retain complete control over our directory 
-structure. In this tutorial, for simplicity, we'll keep all .h and .cc files directly under `src`, except 
-for tests, which belong under `tests`. For larger projects, `jana-generate project MyProjectName` creates
+structure. In this tutorial, for simplicity, we'll keep all .h and .cc files in the topmost directory.
+For larger projects, `jana-generate project MyProjectName` creates
 a much more complex code skeleton. 
 
 To use our new RandomSource as-is, we need to do three things:
-* Add `RandomSource.cc` and `RandomSource.h` to the `QuickTutorial_PLUGIN_SOURCES` list at the top of `src/CMakeLists.txt`
-* Register our `RandomSource` with JANA inside `QuickTutorial.cc` like this:
+* Add `RandomSource.cc` and `RandomSource.h` to the `add_library(...)` line in `CMakeLists.txt`.
+* Register our `RandomSource` with JANA inside `QuickTutorial.cc`
+* Rebuild the cmake project, rebuild the plugin target, and install.
 
+The modified line in the CMakeLists.txt line should look like:
+```
+add_library(QuickTutorial_plugin SHARED QuickTutorial.cc RandomSource.cc RandomSource.h)
 ```
-#include <JANA/JApplication.h>
 
-#include "QuickTutorialProcessor.h"
-#include "RandomSource.h"                         // <- ADD THIS LINE
+The modified `QuickTuorial.cc` file needs to have the new `RandomSource.h` header included so
+it can instantiatie an object and pass it over to the JApplication in the `InitPlugin()` routine.
+The bottom of the file should look like this: 
 
-extern "C" {
-void InitPlugin(JApplication* app) {
+```
+#include <RandomSource.h>                             // <- ADD THIS LINE (probably better to put this at top of file)
 
-    InitJANAPlugin(app);
+extern "C" {
+    void InitPlugin(JApplication *app) {
+        InitJANAPlugin(app);
+        app->Add(new QuickTutorialProcessor);
+        app->Add(new RandomSource("random", app));    // <- ADD THIS LINE
+    }
+}```
 
-    app->Add(new QuickTutorialProcessor);
-    app->Add(new RandomSource("random", app));    // <- ADD THIS LINE
-}
-}
+And finally, rebuild ...
+```
+cd build
+make install
 ```
-* Rebuild the cmake project, rebuild the plugin target, and install.
 
 When we run the QuickTutorial plugin now, we observe that `QuickTutorialProcessor::Process`
 is being called on every event. Note that `Process` is 'seeing' events slightly out-of-order. This is 
@@ -162,7 +154,7 @@ we organize the work we do inside there. This will be discussed in depth later.
 
 Because neither the source nor the processor are doing any 'real work', the events are being processed 
 very quickly. To throttle the rate events get emitted, to whatever frequency we like, we can add a delay 
-inside `GetEvent`. Perhaps we'd like to set the emit frequency at runtime. First, we declare a member variable on 
+inside `GetEvent`. Perhaps we'd even like to set the emit frequency at runtime. First, we declare a member variable on 
 `RandomSource`, initializing it to our preferred default value:
 
 ```
@@ -188,10 +180,10 @@ plugin. This helps prevent namespace collisions.
 
 ```
 void RandomSource::Open() {
-    JApplication* app = GetApplication();
-    app->SetDefaultParameter("random_source:max_emit_freq_hz",            // ADD ME
-                             m_max_emit_freq_hz,                          // ADD ME
-                             "Maximum event rate [Hz] for RandomSource"); // ADD ME
+    JApplication* app = GetApplication(); 								        // <- ADD THIS LINE
+    app->SetDefaultParameter("random_source:max_emit_freq_hz",            // <- ADD THIS LINE
+                             m_max_emit_freq_hz,                          // <- ADD THIS LINE
+                             "Maximum event rate [Hz] for RandomSource"); // <- ADD THIS LINE
 }
 ```
 
@@ -206,9 +198,9 @@ void RandomSource::GetEvent(std::shared_ptr <JEvent> event) {
     event->SetEventNumber(current_event_number++);
     event->SetRunNumber(22);
 
-    /// Slow down event source                                           // ADD ME
-    auto delay_ms = std::chrono::milliseconds(1000/m_max_emit_freq_hz);  // ADD ME
-    std::this_thread::sleep_for(delay_ms);                               // ADD ME
+    /// Slow down event source                                           // <- ADD THIS LINE
+    auto delay_ms = std::chrono::milliseconds(1000/m_max_emit_freq_hz);  // <- ADD THIS LINE
+    std::this_thread::sleep_for(delay_ms);                               // <- ADD THIS LINE
 }
 ```
 

docs/index.md

@@ -24,12 +24,12 @@ options that allow for more complicated reconstruction as your project grows. Th
 run on a laptop for local code development, but to also be highly efficent when deploying to large computing
 sites like [NERSC](http://www.nersc.gov/){:target="_blank"}.
 
-JANA is currently undergoing a complete rewrite. The new version will be JANA 2. The code is not quite ready
-for actual use yet, but you are free to browse around to see how progress is going. The project is 
+JANA has undergone a large rewrite with the newer version dubbed JANA2. The code is now available for use
+and you are free to browse around. The project is 
 [hosted on GitHub](https://github.com/JeffersonLab/JANA2)
 
 ```
-auto tracks = jevent->Get<DTrack>(tracks);
+auto tracks = jevent->Get<DTrack>();
 
 for(auto t : tracks){
   // ... do something with a track

scripts/jana-control.py

@@ -27,7 +27,6 @@
 # import matplotlib.pyplot as plt
 # import numpy as np
 
-# TODO: Allow command line arguments to change host and port numbers
 # -- Globals
 DONE      = False
 PORT      = 11238
@@ -141,9 +140,20 @@ def __init__(self, master=None):
     #=========================
     # init_window
     def init_window(self):
-
+
+        # Find a font family for the banner
+        preferred_fonts = ['Comic Sans MS', 'URW Gothic', 'Courier']
+        available_fonts=list(tkFont.families())
+        self.bannerFont = None
+        for f in preferred_fonts:
+            for af in available_fonts:
+                if af.startswith( f ):
+                    self.bannerFont = tkFont.Font(family=af, size=36)
+                    break
+            if self.bannerFont : break
+        if self.bannerFont == None : self.bannerFont = tkFont.Font(family=preferred_fonts[-1], size=36)
+
         self.labelsFont = tkFont.Font(family="Helvetica", size=16)
-        self.bannerFont = tkFont.Font(family="Comic Sans MS", size=36)
         self.labmap = {}
 
         self.master.title('JANA Status/Control GUI')