Index: R-exts.texi =================================================================== --- R-exts.texi (revision 58859) +++ R-exts.texi (working copy) @@ -245,9 +245,11 @@ @cindex LICENCE file The optional file @file{LICENSE}/@file{LICENCE} contains a copy of the -license to the package. Whereas you should feel free to include a -license file in your @emph{source} distribution, please do not arrange -to @emph{install} yet another copy of the @acronym{GNU} @file{COPYING} +license to the package. Although the @file{DESCRIPTION} file includes +a mandatory field for the license type, most common licenses need to +be filled in with names, dates, and other data, so a full license file +should be included in the @emph{source} distribution. Please do not +arrange to @emph{install} yet another copy of the @acronym{GNU} @file{COPYING} or @file{COPYING.LIB} files but refer to the copies on @uref{http://www.r-project.org/@/Licenses/} and included in the @R{} distribution (in directory @file{share/licenses}). Since files named @@ -301,8 +303,6 @@ * The INDEX file:: * Package subdirectories:: * Package bundles:: -* Data in packages:: -* Non-R scripts in packages:: @end menu @node The DESCRIPTION file, The INDEX file, Package structure, Package structure @@ -713,8 +713,136 @@ @subsection Package subdirectories @cindex Package subdirectories -The @file{R} subdirectory contains @R{} code files, only. The code -files to be installed must start with an @acronym{ASCII} (lower or upper +The @file{R} subdirectory contains @R{} code files, only: See @xref{R code in packages}. + +The @file{man} subdirectory should contain (only) documentation files +for the objects in the package in @dfn{R documentation} (Rd) format. +The documentation filenames must start with an @acronym{ASCII} (lower or +upper case) letter or digit and have the extension @file{.Rd} (the +default) or @file{.rd}. Further, the names must be valid in +@samp{file://} URLs, which means@footnote{More precisely, they can +contain the English alphanumeric characters and the symbols @samp{$ - _ +. + ! ' ( ) , ; @ = &}.} they must be entirely @acronym{ASCII} and not +contain @samp{%}. @xref{Writing R documentation files}, for more +information. Note that all user-level objects in a package should be +documented; if a package @var{pkg} contains user-level objects which are +for ``internal'' use only, it should provide a file +@file{@var{pkg}-internal.Rd} which documents all such objects, and +clearly states that these are not meant to be called by the user. See +e.g.@: the sources for package @pkg{grid} in the @R{} distribution for +an example. Note that packages which use internal objects extensively +should not export those objects from their namespace, when they do not +need to be documented (@pxref{Package namespaces}). + +Having a @file{man} directory containing no documentation files may give +an installation error. + +The @file{R} and @file{man} subdirectories may contain OS-specific +subdirectories named @file{unix} or @file{windows}. + +The sources and headers for the compiled code are in @file{src}, plus +optionally a file @file{Makevars} or @file{Makefile}: See @xref{Compiled code in packages}. + +The @file{data} subdirectory is for data files: @xref{Data in packages}. + +The @file{demo} subdirectory is for @R{} scripts (for running @emph{via} +@code{demo()}) that demonstrate some of the functionality of the +package. Demos may be interactive and are not checked automatically, so +if testing is desired use code in the @file{tests} directory to achieve +this. The script files must start with a (lower or upper case) letter +and have one of the extensions @file{.R} or @file{.r}. If present, the +@file{demo} subdirectory should also have a @file{00Index} file with one +line for each demo, giving its name and a description separated by white +space. (Note that it is not possible to generate this index file +automatically.) + +@cindex .Rinstignore file +The contents of the @file{inst} subdirectory will be copied recursively +to the installation directory. Subdirectories of @file{inst} should not +interfere with those used by @R{} (currently, @file{R}, @file{data}, +@file{demo}, @file{exec}, @file{libs}, @file{man}, @file{help}, +@file{html} and @file{Meta}, and earlier versions used @file{latex}, +@file{R-ex}). The copying of the @file{inst} happens after @file{src} +is built so its @file{Makefile} can create files to be installed. Prior +to @R{} 2.12.2, the files were installed on POSIX platforms with the +permissions in the package sources, so care should be taken to ensure +these are not too restrictive: @command{R CMD build} will make suitable +adjustments. To exclude files from being installed, one can specify a +list of exclude patterns in file @file{.Rinstignore} in the top-level +source directory. These patterns should be Perl-like regular +expressions (see the help for @code{regexp} in @R{} for the precise +details), one per line, to be matched@footnote{case-insensitively on +Windows.} against the file and directory paths, e.g.@: +@file{doc/.*[.]png$} will exclude all PNG files in @file{inst/doc} based on +the (lower-case) extension. + +Note that with the exceptions of @file{INDEX}, +@file{LICENSE}/@file{LICENCE} and @file{NEWS}, information files at the +top level of the package will @emph{not} be installed and so not be +known to users of Windows and Mac OS X compiled packages (and not seen +by those who use @command{R CMD INSTALL} or @command{install.packages} +on the tarball). So any information files you wish an end user to see +should be included in @file{inst}. Note that if the named exceptions +also occur in @file{inst}, the versions in @file{inst} will be that seen +in the installed package. + +@findex CITATION +@cindex citation +One thing you might like to add to @file{inst} is a @file{CITATION} file +for use by the @code{citation} function. + +Subdirectory @file{tests} is for additional package-specific test code, +similar to the specific tests that come with the @R{} distribution. +Test code can either be provided directly in a @file{.R} file, or +@emph{via} a @file{.Rin} file containing code which in turn creates the +corresponding @file{.R} file (e.g., by collecting all function objects +in the package and then calling them with the strangest arguments). The +results of running a @file{.R} file are written to a @file{.Rout} file. +If there is a corresponding@footnote{The best way to generate such a +file is to copy the @file{.Rout} from a successful run of @command{R CMD +check}. If you want to generate it separately, do run @R{} with options +@option{--vanilla --slave} and with environment variable +@env{LANGUAGE=en} set to get messages in English.} @file{.Rout.save} +file, these two are compared, with differences being reported but not +causing an error. The directory @file{tests} is copied to the check +area, and the tests are run with the copy as the working directory and +with @code{R_LIBS} set to ensure that the copy of the package installed +during testing will be found by @code{library(@var{pkg_name})}. Note +that the package-specific tests are run in a vanilla @R{} session +without setting the random-number seed, so tests which use random +numbers will need to set the seed to obtain reproducible results (and it +can be helpful to do so in all cases, to avoid occasional failures when +tests are run). + +If @file{tests} has a subdirectory @file{Examples} containing a file +@code{@var{pkg}-Ex.Rout.save}, this is compared to the output file for +running the examples when the latter are checked. + +Subdirectory @file{exec} could contain additional executable scripts the +package needs, typically scripts for interpreters such as the shell, +Perl, or Tcl. This mechanism is currently used only by a very few +packages, and still experimental. NB: only files (and not directories) +under @file{exec} are installed (and those with names starting with a +dot are ignored), and they are all marked as executable (mode +@code{755}, moderated by @samp{umask}) on POSIX platforms. Note too +that this may not be suitable for executable @emph{programs} since some +platforms (including Mac OS X and Windows) support multiple +architectures using the same installed package directory. + +Subdirectory @file{po} is used for files related to @emph{localization}: +@pxref{Internationalization}. + +@menu +* R code in packages:: +* Compiled code in packages:: +* Data in packages:: +* Non-R scripts in packages:: +@end menu + +@node R code in packages, Compiled code in packages, Package subdirectories, Package subdirectories +@subsubsection R code in packages + +The R code files to be installed must start with an @acronym{ASCII} (lower or upper case) letter or digit and have one of the extensions@footnote{Extensions @file{.S} and @file{.s} arise from code originally written for S(-PLUS), but are commonly used for assembler code. Extension @file{.q} was used @@ -753,6 +881,10 @@ non-ASCII characters. However, non-@acronym{ASCII} character strings may not be usable in some locales and may display incorrectly in others. +A succinct comment at the top of each @file{.R} file is strongly +encouraged to identify the author, copyright, and license terms. This +has proved useful in catching errors where code was copied between +packages that were meant to be distributed under different licenses. @findex library.dynam Various @R{} functions in a package can be used to initialize and @@ -770,35 +902,10 @@ a package it was called (with argument the full path to the installed package) just before the package was detached.} +@node Compiled code in packages, Data in packages, R code in packages, Package subdirectories +@subsubsection Compiled code in packages -The @file{man} subdirectory should contain (only) documentation files -for the objects in the package in @dfn{R documentation} (Rd) format. -The documentation filenames must start with an @acronym{ASCII} (lower or -upper case) letter or digit and have the extension @file{.Rd} (the -default) or @file{.rd}. Further, the names must be valid in -@samp{file://} URLs, which means@footnote{More precisely, they can -contain the English alphanumeric characters and the symbols @samp{$ - _ -. + ! ' ( ) , ; @ = &}.} they must be entirely @acronym{ASCII} and not -contain @samp{%}. @xref{Writing R documentation files}, for more -information. Note that all user-level objects in a package should be -documented; if a package @var{pkg} contains user-level objects which are -for ``internal'' use only, it should provide a file -@file{@var{pkg}-internal.Rd} which documents all such objects, and -clearly states that these are not meant to be called by the user. See -e.g.@: the sources for package @pkg{grid} in the @R{} distribution for -an example. Note that packages which use internal objects extensively -should not export those objects from their namespace, when they do not -need to be documented (@pxref{Package namespaces}). - -Having a @file{man} directory containing no documentation files may give -an installation error. - -The @file{R} and @file{man} subdirectories may contain OS-specific -subdirectories named @file{unix} or @file{windows}. - -The sources and headers for the compiled code are in @file{src}, plus -optionally a file @file{Makevars} or @file{Makefile}. When a package is -installed using @code{R CMD INSTALL}, @command{make} is used to control +When a package is installed using @code{R CMD INSTALL}, @command{make} is used to control compilation and linking into a shared object for loading into @R{}. There are default @command{make} variables and rules for this (determined when @R{} is configured and recorded in @@ -876,104 +983,12 @@ file.copy(files, dest, overwrite = TRUE) @end example -The @file{data} subdirectory is for data files: @xref{Data in packages}. +A succinct comment at the top of each source file is strongly +encouraged to identify the author, copyright, and license terms. -The @file{demo} subdirectory is for @R{} scripts (for running @emph{via} -@code{demo()}) that demonstrate some of the functionality of the -package. Demos may be interactive and are not checked automatically, so -if testing is desired use code in the @file{tests} directory to achieve -this. The script files must start with a (lower or upper case) letter -and have one of the extensions @file{.R} or @file{.r}. If present, the -@file{demo} subdirectory should also have a @file{00Index} file with one -line for each demo, giving its name and a description separated by white -space. (Note that it is not possible to generate this index file -automatically.) +@node Data in packages, Non-R scripts in packages, Compiled code in packages, Package subdirectories +@subsubsection Data in packages -@cindex .Rinstignore file -The contents of the @file{inst} subdirectory will be copied recursively -to the installation directory. Subdirectories of @file{inst} should not -interfere with those used by @R{} (currently, @file{R}, @file{data}, -@file{demo}, @file{exec}, @file{libs}, @file{man}, @file{help}, -@file{html} and @file{Meta}, and earlier versions used @file{latex}, -@file{R-ex}). The copying of the @file{inst} happens after @file{src} -is built so its @file{Makefile} can create files to be installed. Prior -to @R{} 2.12.2, the files were installed on POSIX platforms with the -permissions in the package sources, so care should be taken to ensure -these are not too restrictive: @command{R CMD build} will make suitable -adjustments. To exclude files from being installed, one can specify a -list of exclude patterns in file @file{.Rinstignore} in the top-level -source directory. These patterns should be Perl-like regular -expressions (see the help for @code{regexp} in @R{} for the precise -details), one per line, to be matched@footnote{case-insensitively on -Windows.} against the file and directory paths, e.g.@: -@file{doc/.*[.]png$} will exclude all PNG files in @file{inst/doc} based on -the (lower-case) extension. - -Note that with the exceptions of @file{INDEX}, -@file{LICENSE}/@file{LICENCE} and @file{NEWS}, information files at the -top level of the package will @emph{not} be installed and so not be -known to users of Windows and Mac OS X compiled packages (and not seen -by those who use @command{R CMD INSTALL} or @command{install.packages} -on the tarball). So any information files you wish an end user to see -should be included in @file{inst}. Note that if the named exceptions -also occur in @file{inst}, the versions in @file{inst} will be that seen -in the installed package. - -@findex CITATION -@cindex citation -One thing you might like to add to @file{inst} is a @file{CITATION} file -for use by the @code{citation} function. - -Subdirectory @file{tests} is for additional package-specific test code, -similar to the specific tests that come with the @R{} distribution. -Test code can either be provided directly in a @file{.R} file, or -@emph{via} a @file{.Rin} file containing code which in turn creates the -corresponding @file{.R} file (e.g., by collecting all function objects -in the package and then calling them with the strangest arguments). The -results of running a @file{.R} file are written to a @file{.Rout} file. -If there is a corresponding@footnote{The best way to generate such a -file is to copy the @file{.Rout} from a successful run of @command{R CMD -check}. If you want to generate it separately, do run @R{} with options -@option{--vanilla --slave} and with environment variable -@env{LANGUAGE=en} set to get messages in English.} @file{.Rout.save} -file, these two are compared, with differences being reported but not -causing an error. The directory @file{tests} is copied to the check -area, and the tests are run with the copy as the working directory and -with @code{R_LIBS} set to ensure that the copy of the package installed -during testing will be found by @code{library(@var{pkg_name})}. Note -that the package-specific tests are run in a vanilla @R{} session -without setting the random-number seed, so tests which use random -numbers will need to set the seed to obtain reproducible results (and it -can be helpful to do so in all cases, to avoid occasional failures when -tests are run). - -If @file{tests} has a subdirectory @file{Examples} containing a file -@code{@var{pkg}-Ex.Rout.save}, this is compared to the output file for -running the examples when the latter are checked. - -Subdirectory @file{exec} could contain additional executable scripts the -package needs, typically scripts for interpreters such as the shell, -Perl, or Tcl. This mechanism is currently used only by a very few -packages, and still experimental. NB: only files (and not directories) -under @file{exec} are installed (and those with names starting with a -dot are ignored), and they are all marked as executable (mode -@code{755}, moderated by @samp{umask}) on POSIX platforms. Note too -that this may not be suitable for executable @emph{programs} since some -platforms (including Mac OS X and Windows) support multiple -architectures using the same installed package directory. - -Subdirectory @file{po} is used for files related to @emph{localization}: -@pxref{Internationalization}. - -@node Package bundles, Data in packages, Package subdirectories, Package structure -@subsection Package bundles -@cindex Package bundles - -Support for package bundles was removed in @R{} 2.11.0. - -@node Data in packages, Non-R scripts in packages, Package bundles, Package structure -@subsection Data in packages - The @file{data} subdirectory is for data files, either to be made available @emph{via} lazy-loading or for loading using @code{data()}. (The choice is made by the @samp{LazyData} field in the @@ -1046,8 +1061,8 @@ Lazy-loading is not supported for very large datasets (those which when serialized exceed 2GB). -@node Non-R scripts in packages, , Data in packages, Package structure -@subsection Non-R scripts in packages +@node Non-R scripts in packages, , Data in packages, Package subdirectories +@subsubsection Non-R scripts in packages Code which needs to be compiled (C, C++, FORTRAN, Fortran 95 @dots{}) is included in the @file{src} subdirectory and discussed elsewhere in @@ -1076,6 +1091,12 @@ 2.9 @end example +@node Package bundles, , Package subdirectories, Package structure +@subsection Package bundles +@cindex Package bundles + +Support for package bundles was removed in @R{} 2.11.0. + @node Configure and cleanup, Checking and building packages, Package structure, Creating R packages @section Configure and cleanup