From c905e1401c21657e150f5a3ea74f3d1e43cb170d Mon Sep 17 00:00:00 2001 From: tomeichlersmith Date: Fri, 29 Dec 2023 16:18:08 -0600 Subject: [PATCH] put questions into question block make the blocks collapsible as well so readers only have to read the stuff they want the answers to --- src/faq.md | 43 ++++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/src/faq.md b/src/faq.md index 5db84a51..b45fcd77 100644 --- a/src/faq.md +++ b/src/faq.md @@ -1,7 +1,7 @@ # What the F.A.Q.? Frequent issues and potholes that new collaborators run into while starting their work with LDMX software. -### Running ROOT Macros from the Command Line +~~~admonish question collapsible=true title="Running ROOT Macros from the Command Line" ROOT uses shell-reserved characters in order to mark command line arguments as specific inputs to the function it is parsing and running as a macro. This makes passing these arguments through our shell infrastructure difficult and one needs a hack to get around this. Outside of the container, one might execute a ROOT macro like @@ -15,9 +15,9 @@ ldmx root <-bash: compopt: command not found @@ -119,8 +125,9 @@ chsh -s /usr/local/bin/bash $USER You can double check your current shell's bash version by running `echo $BASH_VERSION`. This answer was based on a helpful [stackexchange answer](https://apple.stackexchange.com/questions/224511/how-to-use-bash-as-default-shell). +~~~ -### I can't compile and I get a "No such file or directory" error. +~~~admonish question collapsible=true title="I can't compile and I get a 'No such file or directory' error." LDMX software is broken up into several different `git` repositories that are then pulled into a central repository _ldmx-sw_ as "submodules". In order for you to get the code in the submodules, you need to tell `git` that you want it. There are two simple ways to do this. 1. You can re-clone the repository, but this time using the `--recursive` flag. @@ -131,8 +138,9 @@ git clone --recursive https://github.com/LDMX-Software/Framework.git ```bash git submodule update --init --recursive ``` +~~~ -### Software complains about not being able to create a processor. (UnableToCreate) +~~~admonish question collapsible=true title="Software complains about not being able to create a processor. (UnableToCreate)" This is almost always due to the library that contains that processor not being loaded. We are trying to have the libraries automatically included by the python templates, but if you have found a python template that doesn't include the library you can do the following in the meantime. @@ -142,8 +150,9 @@ but if you have found a python template that doesn't include the library you can p.libraries.append( 'libMODULE.so' ) # MODULE is the module that your processor is in (for example: Ecal, EventProc, or Analysis) ``` +~~~ -### Software complains about linking a library. (LibraryLoadFailure) +~~~admonish question collapsible=true title="Software complains about linking a library. (LibraryLoadFailure)" Most of the time, this is caused by the library not being found in the common search paths. In order to make sure that the library can be found, you should give the full path to it. ``` @@ -152,8 +161,9 @@ In order to make sure that the library can be found, you should give the full pa p.libraries.append( '/lib/libMODULE.so' ) # MODULE is the module that your processor is in (for example: Ecal, EventProc, or Analysis) ``` +~~~ -### ROOT version mismatch error. +~~~admonish question collapsible=true title="ROOT version mismatch error." This error looks something like this: ``` Error in : version mismatch, /ldmx-sw/install/lib/libEvent.so = 62000, ROOT = 62004 @@ -165,16 +175,19 @@ This makes sure that the dependencies never change. If you need some dependency that isn't in your version of the container, please file an [issue with the docker repository](https://github.com/LDMX-Software/docker/issues/new/choose) to request what's called a "derivative" container. +~~~ -### Parameter 'className' does not exist in list of parameters. +~~~admonish question collapsible=true title="Parameter 'className' does not exist in list of parameters." This error usually occurs when you pass an object that isn't an EventProcessor as an EventProcessor to the Process sequence. A feature that is helpful for debugging your configuration file is the `Process.pause` function: ``` # at the end of your config.py p.pause() #prints your Process configuration and waits for you to press enter before continuing ``` +~~~ -### ldmx-sw cannot find the contents of a file when I _know_ that the file exists +~~~admonish question collapsible=true title="ldmx-sw cannot find the contents of a file when I _know_ that the file exists" Remember that you are running inside of the container, so the file you want to give to the software must be accessible by the container. Some python features that are helpful for making sure the container can find your file are `os.path.fullpath` to get the full path to a file and `os.path.isfile` to check that the file exists. +~~~