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