Warning, /jana2/docs/howto/skeletons.md is written in an unsupported language. File is not indexed.
0001
0002 # Generating code skeletons
0003
0004 JANA provides a script, `$JANA_HOME/bin/jana-generate.py`, which generates code skeletons for
0005 different kinds of JANA components, but also entire project structures. These are intended to
0006 compile and run with zero or minimal modification, to provide all of the boilerplate needed, and
0007 to include comments explaining what each piece of boilerplate does and what the user is expected
0008 to add. The aim is to demonstrate idiomatic usage of the JANA framework and reduce the learning
0009 curve as much as possible.
0010
0011 #### Complete projects
0012 The 'project' skeleton lays out the recommended structure for a complex experiment with multiple
0013 plugins, a domain model which is shared between plugins, and a custom executable. In general,
0014 each experiment is expected to have one project.
0015
0016 ```jana-generate.py project ProjectName```
0017
0018 #### Project plugins
0019 Project plugins are used to modularize some functionality within the context of an existing project.
0020 Not only does this help separate concerns, so that many members of a collaboration can work together
0021 without interfering with another, but it also helps manage the complexity arising from build dependencies.
0022 Some scientific software stubbornly refuses to build on certain platforms, and plugins are a much cleaner
0023 solution than the traditional mix of environment variables, build system variables, and preprocessor macros.
0024 Project plugins include one JEventProcessor by default.
0025
0026 ```jana-generate.py ProjectPlugin PluginNameInCamelCase```
0027
0028
0029 #### Mini plugins
0030 Mini plugins are project plugins which have been stripped down to a single `cc` file. They are useful
0031 when someone wants to do a quick analysis and doesn't need or want the additional boilerplate. They
0032 include one JEventProcessor with support for ROOT histograms. There are two options:
0033
0034 ```
0035 jana-generate.py MiniStandalonePlugin PluginNameInCamelCase
0036 jana-generate.py MiniProjectPlugin PluginNameInCamelCase
0037 ```
0038
0039 #### Standalone plugins
0040 Standalone plugins are useful for getting started quickly. They are also effective when someone wishes to
0041 integrate with an existing project, but want their analyses to live in a separate repository.
0042
0043 ```jana-generate.py StandalonePlugin PluginNameInCamelCase```
0044
0045 #### Executables
0046 Executables are useful when using the provided `$JANA_HOME/bin/jana` is inconvenient. This may be
0047 because the project is sufficiently simple that multiple plugins aren't even needed, or because the project is
0048 sufficiently complex that specialized configuration is needed before loading any other plugins.
0049
0050 ```jana-generate.py Executable ExecutableNameInCamelCase```
0051
0052 #### JEventSources
0053
0054 ```jana-generate.py JEventSource NameInCamelCase```
0055
0056 #### JEventProcessors
0057
0058 ```jana-generate.py JEventProcessor NameInCamelCase```
0059
0060 #### JEventProcessors which output to ROOT
0061
0062 This JEventProcessor includes the boilerplate for creating a ROOT histogram in a specific
0063 virtual subdirectory of a TFile. If this TFile is shared among different `JEventProcessors`,
0064 it should be encapsulated in a JService. Otherwise, it can be specified as a simple parameter.
0065 We recommend naming the subdirectory after the plugin name. E.g. a `trk_eff` plugin contains
0066 a `TrackingEfficiencyProcessor` which writes all of its results to the `trk_eff` subdirectory
0067 of the TFile.
0068
0069 ```jana-generate.py RootEventProcessor ProcessorNameInCamelCase directory_name_in_snake_case```
0070
0071 Note that this script, like the others, does not update your `CMakeLists.txt`. Not only will you
0072 need to add the file to `PluginName_PLUGIN_SOURCES`, but you may need to add ROOT as a
0073 dependency if your project hasn't yet:
0074
0075 ```
0076 find_package(ROOT)
0077 include_directories(${ROOT_INCLUDE_DIRS})
0078 link_directories(${ROOT_LIBRARY_DIR})
0079 target_link_libraries(${PLUGIN_NAME} ${ROOT_LIBRARIES})
0080 ```
0081
0082 #### JFactories
0083
0084 Because JFactories are templates parameterized by the type of JObjects they produce, we need two arguments
0085 to generate them. The naming convention is left up to the user, but the following is recommended. If the
0086 JObject name is 'RecoTrack', and the factory uses Genfit under the hood, the factory name should be
0087 'RecoTrackFactory_Genfit'.
0088
0089 ```jana-generate.py JFactory JFactoryNameInCamelCase JObjectNameInCamelCase```
0090
