general-package-development.Rmd

# General _Bioconductor_ Package Development {#general}

## Version of _Bioconductor_ and <i class="fab fa-r-project"></i>

Package developers should always use the [devel version of _Bioconductor_]['devel' version] and
[_Bioconductor_ packages][biocViews] when developing and testing packages to be contributed.

Depending on the <i class="fab fa-r-project"></i> release cycle, using
[_Bioconductor_][] devel may or may not involve also using the devel version of
<i class="fab fa-r-project"></i>. See the how-to on [using devel version of
Bioconductor]['devel' version] for up-to-date information.

## Correctness, Space and Time {#correctness-space-and-time}

### R CMD build {#r-cmd-build}

[_Bioconductor_][] packages must minimally pass `R CMD build` (or `R CMD INSTALL
--build`) and pass `R CMD check` with no errors and no warnings using a recent
R-devel. Authors should also try to address all errors, warnings, and notes that
arise during build or check.

### BiocCheck {#bioccheck}

Packages must also pass `BiocCheck::BiocCheckGitClone()` and
`BiocCheck::BiocCheck('new-package'=TRUE)` with no errors and no warnings. The
`r BiocStyle::Biocpkg("BiocCheck")` package is a set of tests that encompass
[_Bioconductor_][] Best Practices. Every effort should be made to address any
errors, warnings, and notes that arise during this build or check.

### ERROR, WARNING, and NOTES {#error-warning-and-notes}

The [_Bioconductor_][] team member assigned to review
the package during the submission process will expect all ERROR, WARNINGS, and
NOTES to be addressed from both R CMD build, R CMD check, and BiocCheck. If
there are any remaining, a justification of why they are not corrected will be
expected.


### File names {#file-names}

Do not use filenames that differ only in case, as not all file systems are case-sensitive.

### Package size {#package-size}

The source package resulting from running `R CMD build` should occupy less than
10 MB on disk. If your package includes some screenshots (e.g., in the
vignettes), this limit can be reached quite quickly. Their size can be reduced
(often as much as 70%) with lossy compression using tools such as
[pngquant](https://pngquant.org/) (available as a command line utility and as a
GUI on most systems).

### Check duration {#check-duration}

The package should require less than 10 minutes to run `R CMD check --no-build-vignettes`.
Using the `--no-build-vignettes` option ensures that the vignette is built only once.
^[This is true only for Software Packages.
Experiment Data, Annotation, and Workflow packages are allowed additional space and check time.]

### Memory {#memory}

Due to hardware limitations on the Bioconductor Build System (BBS), it is
recommended that the vignettes, man page examples, and unit tests do not require
more than 8 GB of memory to run. 

### Individual file size {#individual-file-size}

For software packages, individual files must be <= 5MB.
This restriction exists even after the package is accepted and added to the
[_Bioconductor_][] repository. See [data section](#data) for
advice on packages using large data files. 

### Undesirable files {#undesirable-files}

The raw package directory should not contain unnecessary files, system files, or
hidden files such as `.DS_Store`, `.project`, `.git`, cache files, log files,
`*.Rproj`, `*.so`, etc. These files may be present in your local directory but should not be commited to
git (see [`.gitignore`]{#gitignore}). Any files or directories for other
applications (Github Actions, devtool, etc) should ideally be in a different
branch and not submitted to the _Bioconductor_ version of the package. 

## R CMD check environment {#r-cmd-check-environment}

It is possible to activate or deactivate a number of options in `R CMD build` and `R CMD check`.
Options can be set as individual environment variables or they can be [listed in a file](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Checking-and-building-packages).
Descriptions of all the different options available can be found [here](https://cran.r-project.org/doc/manuals/r-devel/R-ints.html#Tools).
[_Bioconductor_][] has chosen to customize some of these options for incoming submission during `R CMD check`.
The file of utilized flags can be downloaded from [<i class="fab fa-github"></i> GitHub](https://github.com/Bioconductor/packagebuilder/blob/master/check.Renviron).
The file can either be placed in a default directory as directed [here](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Checking-and-building-packages) or can be set through environment variable `R_CHECK_ENVIRON` with a command similar to:

```{bash, eval=FALSE}
export R_CHECK_ENVIRON = <path to downloaded file>
```