pre.install creates a "source package" from a "task package", ready for first-time installation using install.pkg. You must have called maintain.packages( mypack) at some point in your R{} session before pre.install( mypack) etc.
patch.install is normally sufficient for subsequent maintenance of an already-installed package (ie you rarely need call install.pkg again). Again, maintain.packages must have been called earlier. It's also expected that the package has been loaded via library() before patch.install is called, but this may not be required. patch.install first calls pre.install and then modifies the installed package accordingly on-the-fly, so there is no need to re-load or re-build or re-install. patch.install also updates the help system with immediate effect, i.e. during the current R{} session. You don't need to call patch.install after every little maintenance change to your package during an R{} session; it's usually only necessary when (i) you want updated help, or (ii) you want to make the changes "permanent". However, it's not a problem to call patch.install quite often. patch.installed is a synonym for patch.install.
It's possible to tweak the source-package-creation process, and this is what 'pre.install.hook...# 95% of the time you just need:
# pre.install( pkg)
# patch.install( pkg)
# Your own hook: pre.install.hook.<>( default.list, <>, ...)
pre.install( pkg, character.only=FALSE, force.all.docs=FALSE,
dir.above.source="+", autoversion=getOption("mvb.autoversion", TRUE),
R.target.version=getRversion(), ...)
patch.installed( pkg, character.only=FALSE, force.all.docs=FALSE, help.patch=TRUE, DLLs.only=FALSE,
update.installed.cache=option.or.default("mvb.update.installed.cache", TRUE),
pre.inst=TRUE, dir.above.source="+", R.target.version=getRversion(),
autoversion=getOption("mvb.autoversion", TRUE))
patch.install(...) # actually the args are exactly the same as for 'patch.installed' .onLoadxxxin its own right, include a flat-format text objectxxx.docin your task package; seedoc2Rd.xxx.docitself won't appear in the packaged object, but will result in documentation forxxxandany other data objects that are given as alias lines.datato access a dataset in the package, and in fact it won't work.has.namespace==TRUE and use.existing.NAMESPACE==FALSEsystem.rdamvbutils.packaging.tools: the "task package" is the directory containing the ".RData" file with the guts of your package, which should be linked into the cd task hierarchy. The "source package" is usually the directory "<pre.install is as follows-- to change it, see Overriding defaults. A basic source package is created in a subdirectory "<flatdoc style documentation, although precedence will be given to any pre-existing Rd files found in an "Rd" subdirectory of your task, which get copied directly into the package. Any "inst", "demo", "tests", "src", "exec", and "data" subdirectories will be copied to the source package, recursively (i.e. including any of their subdirectories). There is no compilation of source code, since only a source package is being created; see also Compiled code below.
Most objects in the task package will go into the source package, but there are usually a few you wouldn't want there: objects that are concerned only with how to create the package in the first place, and ephemeral system clutter such as .Random.seed. The default exceptions are: functions pre.install.hook.<> , .First.task, and .Last.task; data <>.file.exclude.regexes , forced!exports, .required, .Depends, tasks, .Traceback, .packageName, last.warning, .Last.value, .Random.seed, .SavedPlots; and any character vector whose name ends with ".doc".
All pre-existing files in the "man", "src", "tests", "exec", "demo", "inst", and "R" subdirectories of the source-package directory will be removed (unless you have some mlazy objects; see below). If an .Rbuildignore file is present in the task package, it's copied to the package directory, but I've never gotten this feature to work (NB I should include a facility in the pre-install hook for this). To exclude files that would otherwise be copied, i.e. those in "inst/demo/src/data" folders, create a character vector of regexes called <>.file.exclude.regexes ; any file matching any of these won't be copied. If there is a "changes.txt" file in the task package, it will be copied to the "inst" subdirectory of the package, as will any files in the task's own "inst" subdirectory. Similarly, any DESCRIPTION file in the task package will be copied to the source package, after removing any "Built:" line. If there is no DESCRIPTION file in the task package, a default DESCRIPTION file will be created in the package directory, but you'll certainly want to edit it before CRAN release; you can also generate the DESCRIPTION file yourself via the pre.install.hook override. Any "Makefile.*" in the task package will be copied, as will any in the "src" subdirectory (not sure why both places are allowed). No other files or subdirectories in the package directory will be created or removed, but some essential files will be modified.
If a NAMESPACE file is present in the task (usually no need), then it is copied directly to the package. If not, then pre.install will generate a NAMESPACE file by calling make.NAMESPACE, which makes reasonable guesses about what to import, export, and S3methodize. What is & isn't an S3 method is generally deduced OK (see make.NAMESPACE for gruesome details), but you can override the defaults via the pre-install hook. FWIW, since adding the package-creation features to mvbutils, I have never bothered explicitly writing a NAMESPACE file for any of my packages. By default, only documented functions are exported (i.e. visible to the user or other packages); the rest are only available to other functions in your package.
The R{} source file will contain functions only. Any doc and export.me attributes are dropped, but other attributes are kept; in particular, source code is kept in the source attribute.
If any of the Rd files starts with a period, e.g. ".dotty.name", it will be renamed to e.g. "01.dotty.name.Rd" to avoid some problems with RCMD. This should never matter, but just so you know...mvbutils.packaging.tools, cd, doc2Rd, maintain.packages# Workflow for simple case:
cd( task.above.mypack)
maintain.packages( mypack)
# First-time setup, or after major R version changes:
pre.install( mypack)
install.pkg( mypack)
library( mypack)
# ... do stuff
# Subsequent maintenance:
maintain.packages( mypack) # only once per session
lbrary( mypack) # maybe optional
# ...do various things involving changes to mypack
patch.install( mypack) # keep disk image up-to-date
# Prepare copies for distribution
maintain.packages( mypack) # only once per session
# library( mypack) is optional
build.pkg( mypack) # for Linux or CRAN
build.pkg.binary( mypack) # for Windows or MacsRun the code above in your browser using DataLab