Skip to content

Docs: update vignette #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
guideflandre merged 1 commit into from
Jun 2, 2026
Merged

Docs: update vignette #20

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 45 additions & 28 deletions vignettes/BiocExecute.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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;
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -149,7 +148,7 @@ mypkg
│ │ mypkg.R
│ │
│ └───scripts
│ │ template.R
│ │ base_template.R
│
└───tests
│ │ testA.R
Expand All @@ -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).

Expand All @@ -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` |
Expand Down Expand Up @@ -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).
Loading