add example cmake downstream, add comments

Author: m-fila

compile/README.md

@@ -63,3 +63,21 @@ In case the compiled library resides in non-standard location, add its location
 LD_LIBRARY_PATH=JetReconstructionCompiled/lib/:${LD_LIBRARY_PATH} ./jetreconstruction_test
 ```
 
+### Compilation with CMake
+
+The JetReconstruction library comes with a CMake target `JetReconstruction::JetReconstruction`. Example usage in CMake file:
+
+```cmake
+find_package(JetReconstruction REQUIRED)
+
+target_link_libraries(myTarget PUBLIC JetReconstruction::JetReconstruction)
+```
+
+## Limitations
+
+Currently it's not possible to create libraries for different platforms - no cross-compilation!
+
+The library is relocatable given the whole installation tree is moved, including libraries in the `lib/julia/` directory.
+
+It's advised to install the library in a separate directory to avoid possible conflicts.  
+The library must not be installed in the same directory as another Julia package compiled with `PackageCompiler.jl` as they would overwrite the package specific files in `share/julia`.

compile/downstream/CMakeLists.txt

@@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.12)
+
+project(
+  JetReconstruction_downstream
+  LANGUAGES C
+  VERSION 0.1.0)
+
+find_package(JetReconstruction 0.4.3 REQUIRED)
+
+add_executable(jetreconstruction_test jetreconstruction_test.c)
+target_link_libraries(jetreconstruction_test
+                      PUBLIC JetReconstruction::JetReconstruction)
+
+enable_testing()
+add_test(NAME JetReconstructionTest COMMAND jetreconstruction_test)

compile/downstream/README.md

@@ -0,0 +1,3 @@
+# Downstream project example
+
+Example downstream project using C-bindings of JetReconstruction.jl

compile/downstream/jetreconstruction_test.c

@@ -0,0 +1,82 @@
+#include "JetReconstruction.h"
+#include "julia_init.h"
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+
+void printPseudoJet(const jetreconstruction_PseudoJet *jet) {
+  assert(jet != NULL);
+  printf("PseudoJet(%f %f %f %f %ld %f %f %f %f)\n", jet->px, jet->py, jet->pz,
+         jet->E, jet->_cluster_hist_index, jet->_pt2, jet->_inv_pt2, jet->_rap,
+         jet->_phi);
+}
+
+void printHistoryElement(const jetreconstruction_HistoryElement *history) {
+  assert(history != NULL);
+  printf("HistoryElement(%ld %ld %ld %ld %lf %lf)\n", history->parent1,
+         history->parent2, history->child, history->jetp_index, history->dij,
+         history->max_dij_so_far);
+}
+
+void printClusterSequence(const jetreconstruction_ClusterSequence *sequence) {
+  printf("Cluster Sequence Information:\n"
+         "Algorithm: %d\n"
+         "Power: %f\n"
+         "R parameter: %f\n"
+         "Strategy: %d\n"
+         "Initial number of jets: %ld\n"
+         "Total event energy (Qtot): %f\n",
+         sequence->algorithm, sequence->power, sequence->R, sequence->strategy,
+         sequence->n_initial_jets, sequence->Qtot);
+  printf("Number of jets: %zu\n", sequence->jets_length);
+  if (sequence->jets != NULL) {
+    for (size_t i = 0; i < sequence->jets_length; i++) {
+      printPseudoJet(sequence->jets + i);
+    }
+  }
+  printf("History length: %zu\n", sequence->history_length);
+  if (sequence->history != NULL) {
+    for (size_t i = 0; i < sequence->history_length; i++) {
+      printHistoryElement(sequence->history + i);
+    }
+  }
+}
+
+void printJetsResult(const jetreconstruction_JetsResult *results) {
+  assert(results != NULL);
+  for (size_t i = 0; i < results->length; ++i) {
+    printPseudoJet(results->data + i);
+  }
+}
+
+int main(int argc, char *argv[]) {
+  clock_t start_time = clock();
+  init_julia(argc, argv);
+  size_t len = 2;
+  jetreconstruction_PseudoJet particles[2];
+  jetreconstruction_PseudoJet_init(&particles[0], 0.0, 1.0, 2.0, 3.0);
+  jetreconstruction_PseudoJet_init(&particles[1], 1.0, 2.0, 3.0, 4.0);
+
+  jetreconstruction_JetAlgorithm algorithm = JETRECONSTRUCTION_JETALGORITHM_CA;
+  double R = 3.0;
+  jetreconstruction_RecoStrategy strategy = JETRECONSTRUCTION_RECOSTRATEGY_BEST;
+
+  jetreconstruction_ClusterSequence cluster_seq;
+  jetreconstruction_jet_reconstruct(particles, len, algorithm, R, strategy,
+                                    &cluster_seq);
+
+  printClusterSequence(&cluster_seq);
+  jetreconstruction_JetsResult result;
+  jetreconstruction_exclusive_jets_njets(&cluster_seq, 2, &result);
+  printJetsResult(&result);
+
+  jetreconstruction_JetsResult_free_members(&result);
+  jetreconstruction_ClusterSequence_free_members(&cluster_seq);
+  shutdown_julia(0);
+
+  clock_t end_time = clock();
+  double time_spent = (double)(end_time - start_time) / CLOCKS_PER_SEC;
+  printf("Execution time: %f seconds\n", time_spent);
+  return 0;
+}

compile/precompile_execution.jl

@@ -1,3 +1,5 @@
+# Dummy code to call and cache compilation of all C-bindings
+# The numeric values doesn't make sense and are used only to select correct dispatch
 
 using JetReconstruction
 using JetReconstruction.C_JetReconstruction: jetreconstruction_PseudoJet_init,