Description Usage Arguments Details Value Side effects Note Author(s) References See Also Examples
source()
all of the source files and data files in a package
into an environment on the search path. If an environment is not
already attached by a previous invocation of source.pkg()
, one
will be created and attached. It also loads DLLs if requested, and if
those DLLs can be found. This function is intended for use in code
development, in situations where code from a package can be tested
without worrying about imports, namespaces, etc.
1 2 3 4 5 6 7 8 | source.pkg(pkg.dir = getOption("scriptests.pkg.dir", "pkg"),
pattern = ".*",
suffix = "\\.R$",
dlls = c("no", "check", "build", "src"),
unload=FALSE, pos = NA, all = FALSE,
reset.function.envirs=TRUE,
path=getOption("scriptests.pkg.path", default=getwd()),
get.sccv=getOption('source.pkg.sccversion'))
|
pkg.dir |
The directory where the package code lives. This is remembered and the same
value used as the default in subsequent invocations. This can be
different from the package name, which is read from |
pattern |
A regular expression specifying the R files to source |
suffix |
The suffix for the R code files. Files are sourced
only if they match both |
dlls |
Indicates where to look for DLLs or shared-objects:
|
pos |
Which environment on the search path to source R code into |
unload |
Should compiled object files be unloaded? |
all |
If |
reset.function.envirs |
If |
path |
The file system path to the directory in which the
package is located. Can be a semi-colon separated list of paths.
The initial default for |
get.sccv |
The name of the program that outputs the
source-code-control version number, e.g., for SVN, |
The package directory (pkg.dir
) does not need to be the same as
the package name. The package name (refered to here as
pkg.name
) is found by reading the DESCRIPTION
file.
All the objects created by the .R
files are created in a
special environment named pkgcode:<pkg.name>
. If this environment
does not already exist, it will be created and attached to the search
path in position pos
. If it does exist, no attempt is made to
clean it before sourcing the .R
files. All functions and
objects defined in the .R
files will be visible – namespaces
are not implemented.
The easiest way to use this function is when the working directory of
the R session is the directory where each package lives, i.e., the R
code for package mypackage
will be in the directory
./mypackage/R
(relative to the working directory of the R
session.) However, if the package directory is located elsewhere,
supply it as path=
, and this will be remembered for future
invocations of source.pkg()
.
This function does not attempt to replicate all the actions involved in creating and attaching a package. It does the following:
creates a environment named pkgcode:<pkg.name>
where
<pkg.name>
is the name of the package (if it doesn't already exist)
looks for a Depends
line in the DESCRIPTION
file
and loads specified packages
looks for .R
files in the R
subdirectory of the package, and, as appropriate, the R/windows
or R/unix
subdirectories, and uses sys.source()
to
read these into the pkgcode:<pkg.name>
environment. If there is a
Collate
field in the DESCRIPTION
files, this is used to
sort the files before sourcing them.
looks for .Rdata
and .rda
files in the
data
subdirectory, and uses load()
to
read these into the pkgcode:<pkg.name>
environment
if dlls=="check"
(not the default), source.pkg()
looks for DLLs (SO files under Unix) in the directory left by R
CMD check <pkg.dir>
, i.e., in <pkg.dir>.Rcheck/<pkg.name>/libs
or <pkg.name>.Rcheck/<pkg.name>/libs
, and uses
dyn.load()
to load these DLLs. If the DLL was already loaded
(as indicated by getLoadedDLLs()
), dyn.unload()
is
called first. Be aware that unloading and reloading a DLL is not a
reliable operation under many OS's, and even when the call completes
without apparent error, the R session can be corrupted.
This function is executed for its side effects, which may include
attaching a new environment to the search path, or moving an existing
one, and reading function and object definitions into that
environment. source.pkg()
returns as its value a list of the
problems encountered when sourcing the files.
An environment is created and attached to the search path (or if it
already exists, it is modified.)
A variable named scriptests.pkg.dir
is set in the global
environment to the directory of the package whose code was sourced.
If reset.function.envirs=FALSE
is supplied, the environments on
the functions sourced will be the environment where they live on the
search path. Functions with their environment set like this will not
be able to see objects in the global environment or in any environment
earlier on the search path. The default behavior of setting their
environment to be the global environment produces behavior that is
more similar to when the functions are sourced directly into the
global environment.
Tony Plate tplate@acm.org
Similar ideas in an R-devel post by Barry Rowlingson:
http://n4.nabble.com/Lightweight-package-idea-td924000.html#a924000
(link no longer active)
Hadley Wickham source_package() function
http://gist.github.com/180883
, reads DESCRIPTION, loads dependencies, respects
collation order (link no longer active)
runtests()
shares the options()
variables
scriptests.pkg.dir
and scriptests.pkg.path
that provide
defaults for the pkg.dir
and path
arguments.
scriptests-package gives and overview of the package.
1 2 3 4 5 6 7 8 9 10 11 12 | ## Not run:
# sourcing the code in a package stored in <mypackage>/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>")
# sourcing the code in a package stored in path/to/dir/<mypackage>/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>", path="path/to/dir")
# sourcing the code in a package stored in pkg/{DESCRIPTION,R,man,tests}:
# where "pkg" is unrelated to the name of the pacakage
source.pkg("pkg", path="path/to/dir")
# sourcing the code in a package stored in <mypackage>/pkg/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>", path="$PKG/pkg")
## End(Not run)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.