diff --git a/vignettes/BiocExecute.Rmd b/vignettes/BiocExecute.Rmd index 9df5733..ac70575 100644 --- a/vignettes/BiocExecute.Rmd +++ b/vignettes/BiocExecute.Rmd @@ -29,7 +29,7 @@ library("BiocExecute") This project was initiated during the [EuroBioC26 Hackathon](https://github.com/BiocCodingCollaborations/EuroBioc2026_Hackathon). -[Vision](https://github.com/BiocCodingCollaborations/EuroBioc2026_Hackathon#commandline-executables-for-bioconductor-functions-and-scripts) +[GitHub repo](https://github.com/BiocCodingCollaborations/EuroBioc2026_Hackathon#commandline-executables-for-bioconductor-functions-and-scripts) # Motivation @@ -40,7 +40,7 @@ documented, and their quality is ensured through the use of BiocCheck. This package aims to further improve Bioconductor software FAIRness, by making them usable in the command line. -* Findability: xxx; +* Findability: not applicable; * Accessibility: allows more users to use Bioconductor packages, in a wider variety of setups; @@ -52,22 +52,22 @@ tools; workflow manager. Package users and developers can both benefit from this setup: users can use -Bioconductor tools out side of R scripts and integrate them in their own +Bioconductor tools outside of R scripts and integrate them in their own workflows, and package developers can benefit from a wider range of users. Overall, Bioconductor software can gain visibility among a larger community of bioinformaticiens. -Light weight, relies on existing packages +Lightweight, relies on existing packages (`Rapp`). # How to use executables -Here's a quick example of how you would call the function `name(x, y)` from -the package `pkgExample`: +Here's a quick example of how you would call the tool `name(x, y)` from +the package `pkgExample` as a package _user_: -First, the user needs to make sure the package functions are executable: +First, the user needs to make sure the package executables are available: ```{r inst, eval = FALSE} -BiocExecute::installExecs("pkgExample") +BiocExecute::execInstall("pkgExample") ``` And now call those functions from within the terminal: @@ -77,14 +77,14 @@ pkgExample --help pkgExample name -x Bilbo -y Baggins ``` -# How to create executables +# How to create executables as a maintainer -`BiocExecute` uses `Rapp` to make your package functions executable. In the -coming sections we will show the different ways `Rapp` includes arguments to be -called in the CLI. Note that `Rapp` by itself works with scripts in which the -first line is defined as `#!/usr/bin/env Rapp`. You should **_NOT_** include -this line in your scripts ! This is handled internally as it is bundled in the -`BiocExecute` package. +`BiocExecute` uses `Rapp` to make your package functions/scripts executable. In +the coming sections we will show the different ways `Rapp` includes arguments +to be called in the CLI. Note that `Rapp` by itself works with scripts in which +the first line is defined as `#!/usr/bin/env Rapp`. You should **_NOT_** +include this line in your scripts ! This is handled internally as it is bundled +in the `BiocExecute` package. The executables can have many ranges, from a simple function call to an entire complex workflow. Note that bigger workflows mean more parameters to call in @@ -99,12 +99,11 @@ for workflows that are repeatedly used across different user cases. ## Create a script An _R_ package that has executables should include them in its `exec/scripts/` -directory. The maintainer of a package should then call -`BiocExecute::execCompile()` to create the file `packageName.R` in the `exec/` -directory. +directory. `BiocExecute` has all the necessary functions to create these +folders, scripts and more. -For instance, the name of my package is `mypkg`. In its root directory, I don't -have an `exec` directory: +For instance, suppose the name of my package is `mypkg`. In its root directory, +I don't have an `exec` nor a `scripts` folder: ```{r tree, eval = FALSE} mypkg @@ -129,7 +128,7 @@ To create the necessary files, I use: ```{r createSkeleton, eval = FALSE} ## From the root directory -skeletonCli("./") +execSkeleton() ``` Now, my directory tree looks like this: @@ -149,7 +148,7 @@ mypkg │ │ mypkg.R │ │ │ └───scripts -│ │ template.R +│ │ base_template.R │ └───tests │ │ testA.R @@ -159,15 +158,30 @@ mypkg │ myVignette.Rmd ``` -In the `exec` directory, there is a file called `mypkg.R`. This file is built -by compiling all scripts in `exec/scripts/`. It is this file that is -executable and should not be edited by hand as it will be overwritten by -`combineExecs()`. +For now, there is a simple template in the `scripts` folder. The same template +can be created using `execTemplate()`. + +The maintainer of a package should then create the scripts with functions or +workflows that he/she wishes to make executable on the CLI. + +Once the `exec/scripts/` are created, you should (in order from the root +directory): + +1. Call `execCompile()` to build the actual executable script. This file will + be called by its package name and it will be written in the `exec` folder. + Do not edit this file by hand, it is likely to be overwritten. +2. Call `devtools::install()` to re-install the package with the executables. +3. Call `execInstall("mypkg")` or a vector of packages to make the executables + available in the CLI. To remove those, call `execUninstall("mypkg")`. To + make the executables available system-wise (with sudo access), use the + `destdir` parameter. + +Your package functions/tools are now available in the CLI ! ### Scripts files The files in the `exec/scripts/` directory are at the core of the available -executables. One script correcsponds to one command, which can be a simple +executables. One script corresponds to one command, which can be a simple function or even a whole workflow. These scripts are combined and compiled into the main executable file in `exec/` (see section above). @@ -186,7 +200,7 @@ summarises the most common ones: |---|---| | `foo <- ""` | Option: `app --foo value` | | `foo <- NULL` | Positional argument: `app foo-value` | -| `foo <- TRUE` | Boolean switch: `app --foo` / `app --no-foo` | +| `foo <- TRUE` | Boolean switch: `app --foo=true` / `app --foo=true` | | `foo <- c()` | Repeatable option (raw strings): `app --foo a --foo b` | | `foo <- list()` | Repeatable option (parsed values): `app --foo 1 --foo 2` | | `switch("", cmd1 = {}, cmd2 = {})` | Subcommands: `app cmd1 --help` | @@ -225,6 +239,9 @@ count-words myfile.txt --word hello --verbose count-words --help ``` +Use `execTemplate()` to create a template script with the different parameters +to facilitate writing your scripts. + For a full description of all available fields and advanced patterns such as nested subcommands, refer to the [`Rapp` GitHub page](https://github.com/r-lib/Rapp).