Replace generic names when bootstrapping templates

Close #128

.github/workflows/test.yml

@@ -67,7 +67,7 @@ jobs:
           cd ~/work
           git config --global user.name Tester
           git config --global user.email [email protected]
-          nix run github:jacg/nain4#bootstrap-client-project my-project
+          nix run github:jacg/nain4#bootstrap-client-project my-project name-chosen-by-me "description of my project"
           cd my-project
           nix develop -c just | tee just-output
           PATTERN="end of event 10"

doc/src/how-to/start-a-nain4-based-project.md

@@ -8,55 +8,64 @@ not, please see [Install nix](./install-nix.md).
 In order to create a `nain4`-based project use `bootstrap-client-project` like this:
 
 ```bash
-nix run github:jacg/nain4#bootstrap-client-project path/to/your/project
+nix run github:jacg/nain4#bootstrap-client-project path/to/your/project your-chosen-name "one line project description"
 ```
-
-where `path/to/your/project` should not exist before you run the command.
-
+where
++ `path/to/your/project` should not exist before you run the command.
++ `your-chosen-name` should be replaced with a name of your choice: this should
+  be a valid identifier in both `bash` and the `Nix` language, so, roughly
+  speaking, it should not contain any spaces, slashes or other dodgy characters.
+  It will be used to name various things within your project.
++ `"one line project description"` should be replaced with some text of your
+  choice. Don't forget the quotes.
 
 ## Basic usage
-+ `just run 100`: run the application in batch mode with `/run/beamOn 100`
-+ `just run macs/run.mac`: run the application using the macro file `macs/run.mac`
-+ `just run`: run the application with the interactive GUI
-  WARNING: this will probably crash unless you are running on
+
++ `just run -n 100`: run the application in batch mode with `/run/beamOn 100`
++ `just run -g`: run the application with the interactive GUI
+  WARNING: unless you are running on
   + `NixOS`
-  + `macOS`
-  To run the GUI on other OSes you need to use a graphics hardware
-  abstraction helper. There is a `just` recipe which automatically
-  includes this for you:
-  ```bash
-  just view
-  ```
-  The first time you use it, it will take a while to compile.
+  + `macOS` this will probably take a long time the first time you try it, as it
+  will download and compile `nixGL` which is used to detect graphics hardware
+  automatically and guarantee the presence of the required graphics drivers. On
+  subsequent runs, this overhead will disappear.
++ TODO: describe the early/late CLI options
++ TODO: describe the macro path CLI options
 
 ## Project contents
 
 Your bootstrapped project will contain the following files
 
-// TO BE UPDATED WITH TESTS
 ```
-your-project-folder
+path/to/your/project
+├── execute-with-nixgl-if-needed.sh
 ├── flake
-│   └── outputs.nix
+│  └── outputs.nix
 ├── flake.lock
 ├── flake.nix
 ├── justfile
 ├── macs
-│   ├── run.mac
-│   └── vis.mac
-└── src
-    ├── CMakeLists.txt
-    └── n4app.cc
+│  ├── early-cli.mac
+│  ├── early-hard-wired.mac
+│  ├── late-cli.mac
+│  ├── late-hard-wired.mac
+│  ├── run.mac
+│  ├── vis.mac
+│  └── vis2.mac
+├── run-each-test-in-separate-process.sh.in
+├── src
+│  ├── LXe.cc
+│  ├── LXe.hh
+│  ├── meson.build
+│  └── n4app.cc
+└── test
+   ├── catch2-main-test.cc
+   ├── meson.build
+   ├── test-catch2-demo.cc
+   └── test-LXe.cc
 ```
 
-+ `src/n4app.cc` contains the entire c++ source code of your
-  project. As the project grows, you may wish to break this up into
-  smaller source files. You can add as many header (`.hh`) and
-  implementation (`.cc`) files as you wish.
-
-+ `src/CMakeLists.txt` is responsible for the details of the build
-  process. If you do not change the directory structure of your
-  project, you should not need to change this file.
++ TODO: discuss the contents of `src` and `test`
 
 + The `macs` directory contains Geant4 macro files, used to provide
   some app configuration parameters at runtime.

flake/outputs.nix

@@ -131,6 +131,19 @@
       # nix run github:jacg/nain4#bootstrap-client-project project-name author etc
       program = "${pkgs.writeShellScript "bootstrap.sh" ''
         DIRECTORY=$1
+        BASE_NAME=$2
+        DESCRIPTION=$3
+        if [[ -z $DESCRIPTION ]];
+        then
+          echo Missing argument to bootstrap-client-project
+          echo
+          echo Usage:
+          echo
+          echo "REQUIRED  first argument: directory where new project will be placed                   provided: $DIRECTORY"
+          echo "REQUIRED second argument: project identifier \(may not contain spaces, slashes, etc.\) provided: $BASE_NAME"
+          echo "REQUIRED  third argument: IN QUOTES single-line description of project"
+          exit 1
+        fi
         mkdir -p $DIRECTORY
         FQ_DIRECTORY=$(${pkgs.coreutils}/bin/readlink -f $DIRECTORY)
         ${pkgs.coreutils}/bin/cp -Tr ${self}/templates/basic                                    $FQ_DIRECTORY
@@ -140,6 +153,21 @@
         cd           $FQ_DIRECTORY
         ${pkgs.ripgrep}/bin/rg "ANCHOR" --files-with-matches . | ${pkgs.findutils}/bin/xargs ${pkgs.gnused}/bin/sed -i '/ANCHOR/d'
 
+        REPLACE () {
+          OLD=$1
+          NEW=$2
+          ${pkgs.ripgrep}/bin/rg "$OLD" --files-with-matches . | ${pkgs.findutils}/bin/xargs ${pkgs.gnused}/bin/sed -i "s|$OLD|$NEW|g"
+        }
+        REPLACE "CHANGEME-EXE"                           ''${BASE_NAME}
+        REPLACE "CHANGEME-PROJECT-NAME"                  ''${BASE_NAME}
+        REPLACE "CHANGEME-PROJECT-NAME-TESTS"            ''${BASE_NAME}-tests
+        REPLACE "CHANGEME-PROJECT-TEST-EXE"              ''${BASE_NAME}-test
+        REPLACE "CHANGEME-PACKAGE"                       ''${BASE_NAME}
+        REPLACE "CHANGEME-APP"                           ''${BASE_NAME}
+        REPLACE "CHANGEME-ONE-LINE-PROJECT-DESCRIPTION" "''${DESCRIPTION}"
+
+        #${pkgs.ripgrep}/bin/rg "CHANGEME-EXE" --files-with-matches . | ${pkgs.findutils}/bin/xargs ${pkgs.gnused}/bin/sed -i "s|CHANGEME-EXE|$ROOT|g"
+
         git -c init.defaultBranch=master init -q
         # TODO: protect against user not having set git user.{name,email}
         git add .

templates/basic/flake.nix

@@ -1,6 +1,5 @@
 {
-  #CHANGEME-flake-description: keep it short (1 line).
-  description = "flake.nix line 2: Change this to describe your project";
+  description = "CHANGEME-ONE-LINE-PROJECT-DESCRIPTION";
 
   inputs = {
     nain4  .url     = "github:jacg/nain4";

templates/basic/flake/outputs.nix

@@ -7,27 +7,26 @@
 
   in {
 
-    packages.default = self.packages.CHANGEME-my-package;
+    packages.default = self.packages.CHANGEME-PACKAGE;
 
-    # Executed by `nix run <URL of this flake>#CHANGEME-my-package -- <args?>`
+    # Executed by `nix run <URL of this flake>#CHANGEME-PACKAGE -- <args?>`
     # TODO: switch to clang environment
-    packages.CHANGEME-my-package = pkgs.stdenv.mkDerivation {
-      # CHANGEME-pname: replace "CHANGEME-my-package" with a name better-suited to your project
-      pname = "CHANGEME-my-package";
+    packages.CHANGEME-PACKAGE = pkgs.stdenv.mkDerivation {
+      pname = "CHANGEME-PACKAGE";
       version = "0.0.0";
       src = "${self}/src";
       nativeBuildInputs = [];
       buildInputs = [ nain4.packages.nain4 ];
     };
 
     # Executed by `nix run <URL of this flake> -- <args?>`
-    apps.default = self.apps.CHANGEME-my-app;
+    apps.default = self.apps.CHANGEME-APP;
 
-    # Executed by `nix run <URL of this flake>#CHANGEME-my-app`
-    apps.CHANGEME-my-app = let
+    # Executed by `nix run <URL of this flake>#CHANGEME-APP`
+    apps.CHANGEME-APP = let
       g4-data = nain4.deps.g4-data-package;
-      CHANGEME-wrap-my-package = pkgs.writeShellScriptBin "CHANGEME-my-app" ''
-        export PATH=${pkgs.lib.makeBinPath [ self.packages.CHANGEME-my-package ]}:$PATH
+      CHANGEME-APP-app-package = pkgs.writeShellScriptBin "CHANGEME-APP" ''
+        export PATH=${pkgs.lib.makeBinPath [ self.packages.CHANGEME-PACKAGE ]}:$PATH
         # export LD_LIBRARY_PATH=${pkgs.lib.makeLibraryPath [ nain4.packages.geant4 ] }:$LD_LIBRARY_PATH
 
         # TODO replace manual envvar setting with with use of packages' setupHooks
@@ -43,33 +42,33 @@
         export G4INCLDATA="${g4-data.G4INCL}/share/Geant4-11.0.4/data/G4INCL1.0"
         export G4ENSDFSTATEDATA="${g4-data.G4ENSDFSTATE}/share/Geant4-11.0.4/data/G4ENSDFSTATE2.3"
 
-        exec CHANGEME-my-n4-prog --macro-path ${self}/macs "$@"
+        exec CHANGEME-EXE --macro-path ${self}/macs "$@"
       '';
-    in { type = "app"; program = "${CHANGEME-wrap-my-package}/bin/CHANGEME-my-app"; };
+    in { type = "app"; program = "${CHANGEME-APP-app-package}/bin/CHANGEME-APP"; };
 
 
     # Used by `direnv` when entering this directory (also by `nix develop <URL to this flake>`)
     devShell = self.devShells.clang;
 
     # Activated by `nix develop <URL to this flake>#clang`
     devShells.clang = pkgs.mkShell.override { stdenv = nain4.packages.clang_16.stdenv; } {
-      name = "my-nain4-app-clang-devenv";
+      name = "CHANGEME-PROJECT-NAME-clang-devenv";
       packages = nain4.deps.dev-shell-packages ++ [ nain4.packages.clang_16 ];
     };
 
     # Activated by `nix develop <URL to this flake>#gcc`
     devShells.gcc = pkgs.mkShell {
-      name = "my-nain4-app-gcc-devenv";
+      name = "CHANGEME-PROJECT-NAME-gcc-devenv";
       packages = nain4.deps.dev-shell-packages;
     };
 
     # 1. `nix build` .#singularity
     # 2. `scp result <me>@lxplus7.cern.ch:hello.img`
     # 3. [on lxplus] `singularity run hello.img`
     packages.singularity = pkgs.singularity-tools.buildImage {
-      name = "test";
-      contents = [ self.apps.CHANGEME-my-app.program ];
-      runScript = "${self.apps.CHANGEME-my-app.program} $@";
+      name = "CHANGEME-PROJECT-NAME";
+      contents = [ self.apps.CHANGEME-APP.program ];
+      runScript = "${self.apps.CHANGEME-APP.program} $@";
       diskSize = 10240;
       memSize = 5120;
     };

templates/basic/justfile

@@ -26,7 +26,7 @@ build:
 
 run *ARGS: build
   #!/usr/bin/env sh
-  sh execute-with-nixgl-if-needed.sh ./install/app/bin/CHANGEME-my-n4-prog "$@"
+  sh execute-with-nixgl-if-needed.sh ./install/app/bin/CHANGEME-EXE "$@"
   exit $?
 
 clean:

templates/basic/src/meson.build

@@ -1,4 +1,4 @@
-project( 'my-n4-project'
+project( 'CHANGEME-PROJECT-NAME'
        , 'cpp'
        , version : 'v0.0.0'
        , default_options : [ 'buildtype=debugoptimized'
@@ -39,7 +39,7 @@ my_app_sources = ['n4app.cc', 'LXe.cc']
 geant4_include = geant4.get_variable(cmake    : 'Geant4_INCLUDE_DIRS')
 nain4_include  =  nain4.get_variable(pkgconfig: 'includedir'         )
 
-my_app_exe = executable( 'CHANGEME-my-n4-prog'
+my_app_exe = executable( 'CHANGEME-EXE'
                        , my_app_sources
                        , include_directories: [my_app_include, nain4_include, geant4_include]
                        , dependencies       : my_app_deps

templates/basic/test/meson.build

@@ -1,4 +1,4 @@
-project( 'my-n4-project-tests'
+project( 'CHANGEME-PROJECT-NAME-TESTS'
        , 'cpp'
        , version : 'v0.0.0'
        , default_options : [ 'buildtype=debugoptimized'
@@ -46,7 +46,7 @@ c2_demo_sources = ['catch2-main-test.cc', 'test-catch2-demo.cc']
 geant4_include = geant4.get_variable(cmake    : 'Geant4_INCLUDE_DIRS')
 nain4_include  =  nain4.get_variable(pkgconfig: 'includedir'         )
 
-test_executable = 'CHANGEME-my-n4-test'
+test_executable = 'CHANGEME-TEST-EXE'
 demo_executable = 'catch2-demo-test'
 
 my_test_exe = executable( test_executable