EXPERIMENTAL -- USE WITH CAUTION. This function will only create the
necessary source files so that all the code can be used (and installed) like an R package.
This function does not install anything (e.g., devtools::install). After
running this function, simInit will automatically detect that this is now
a package and will load the functions (via pkgload::load_all) from the source files.
This will have the effect that it emulates the "non-package" behaviour of a
SpaDES module exactly. After running this function, current tests show no
impact on module behaviour, other than event-level and module-level Caching will show
changes and will be rerun. Function-level Caching appears unaffected.
In other words, this should cause no changes to running the module code via
simInit and spades.
convertToPackage(
module = NULL,
path = getOption("spades.modulePath"),
buildDocuments = TRUE
)Character string of module name, without path
Character string of modulePath. Defaults to getOption("spades.modulePath").
A logical. If TRUE, the default, then the documentation
will be built, if any exists, using roxygen2::roxygenise.
Invoked for its side effects. There will be a new or modified
DESCRIPTION file in the root directory of the module. Any functions that
were in the main module script (i.e., the .R file whose filename is the name of
the module and is in the root directory of the module) will be moved to individual
.R files in the R folder. Any function with a dot prefix will have the
dot removed in its respective filename, but the function name is unaffected.
Currently, SpaDES.core does not install the package under any circumstances.
It will load it via pkgdown::load_all, and optionally (option("spades.moduleDocument" = TRUE))
build documentation via roxygen2::roxygenise within the simInit call.
This means that any modifications to source code
will be read in during the simInit call, as is the practice when a module
is not a package.
invoked for the side effect of converting a module to a package
This will move all functions that are not already in an .R file
in the R folder into that folder, one function per file, including the
doEvent.xxx function. It will not
touch any other functions already in the "R" folder. It will also create
and fill a minimal DESCRIPTION file. This will leave the defineModule
function call as the only code in the main module file. This defineModule
and a doEvent.xxx are the only 2 elements that are required for an R
package to be considered a SpaDES module. With these changes, the module should
still function normally, but will be able to act like an
R package, e.g., for writing function documentation with roxygen2,
using the testthat infrastructure, etc.
This function is intended to be run once for a module that was created using
the "standard" SpaDES module structure (e.g., from a newModule call). There
is currently no way to "revert" the changes from R (though it can be done using
version control utilities if all files are under version control, e.g., GitHub).
Currently SpaDES.core identifies a module as being a package if it has
a DESCRIPTION file, or if it has been installed to the .libPaths()
e.g., via devtools::install or the like. So one can simply remove the
package from .libPaths and delete the DESCRIPTION file and
SpaDES.core will treat it as a normal module.
The only function that will be exported by default is the doEvent.xxx,
where xxx is the module name. If any other module is to be exported, it must
be explicitly exported with e.g., @export, and then building the NAMESPACE
file, e.g., via devtools::document(moduleRootPath). NOTE: as long as all
the functions are being used inside each other, and they all can be traced back
to a call in doEvent.xxx, then there is no need to export anything else.
The DESCRIPTION file that is created (destroying any existing DESCRIPTION
file) with this function will have
several elements that a user may wish to change. Notably, all packages that were
in reqdPkgs in the SpaDES module metadata will be in the Imports
section of the DESCRIPTION. To accommodate the need to see these functions,
a new R script, imports.R will be created with @import for each
package in reqdPkgs of the module metadata. However, if a module already has used
@importFrom for importing a function from a package, then the generic
@import will be omitted for that (those) package(s).
So, a user should likely follow standard R package
best practices and use @importFrom to identify the specific functions that
are required within external packages, thereby limiting function name collisions
(and the warnings that come with them).
Other elements of a standard DESCRIPTION file that will be missing or possibly
inappropriately short are Title, Description, URL,
BugReports.
There is no need to "install" the source code as a package because simInit
will load it on the fly. But, there may be reasons to install it, e.g., to have
access to individual functions, help manual, running tests etc. To do this,
simply use the devtools::install(pathToModuleRoot). Even if it is installed,
simInit will nevertheless run pkgload::load_all to ensure the
spades call will be using the current source code.
if (requireNamespace("ggplot2") && requireNamespace("pkgload") ) {
tmpdir <- tempdir2()
newModule("test", tmpdir, open = FALSE)
convertToPackage("test", path = tmpdir)
pkgload::load_all(file.path(tmpdir, "test"))
pkgload::unload("test")
}
#> New module test created at /tmp/RtmpoLaiAE/reproducible/8UGwfmXe
#> * edit module code in test.R
#> * write tests for your module code in tests/
#> * describe and document your module in test.Rmd
#> * tell others how to cite your module by editing citation.bib
#> * choose a license for your module; see LICENSE.md
#> New/updated DESCRIPTION file is: /tmp/RtmpoLaiAE/reproducible/8UGwfmXe/test/DESCRIPTION
#> Building documentation
#> First time using roxygen2. Upgrading automatically...
#> Setting `RoxygenNote` to "7.3.1"
#> ℹ Loading test
#> Writing NAMESPACE
#> ℹ Loading test