Module:Building R Packages Part II

(1)

Paper:Advanced R

Module:Building R Packages Part II

1 / 20

(2)

Development Team

Principal investigator: Prof. Bhaswati Ganguli, Professor, Department of Statistics, University of Calcutta Paper co-ordinator: Dr. Abhra Sarkar,Duke University Content writer: Rimli Sengupta

Content writer: Moumita Chatterjee,West Bengal State University Content reviewer: Dr. Santu Ghosh,Shri Ramachandra University

(3)

Edit Description File

I The root folder of the package contains at least a DESCRIPTION file and a NAMESPACE file.

I DESCRIPTION : Package information including dependencies.

I NAMESPACE : List of functions exposed to end user and functions imported from other packages.

I NEWS : What has been updated in each version.

I LICENSE : Copyright information.

I README : Basic description of package.

3 / 20

(4)

Edit Other Files :

I Go back to the mypkg-package.Rd file.

I Edit it to get rid of the text that is not in sections.

I You can also add some simple descriptions and remove some of the optional elements.

I Next edit all the files for each function and the help file for the data.

I Next edit the files f.Rd, g.Rd, sample df.Rd and sample norm.Rd.

(5)

Final Step to build a package

I You have two options to build your package.

I You can build the package for CRAN or you can build for yourself and for other windows users.

I When you are building for CRAN, build and check.

I Assure that you passed all the CRAN tests.

5 / 20

(6)

Final Step to build a package

I The output is a ”tar.gz” file which you will upload to CRAN.

I Then the process will be repeated and your source will be used to build a OSX binary and a windows binary.

I Windows binaries are in zip files.

I So, write all documents and then pass all checks.

I Then build the package again for windows and produce a ’zip’

binary.

(7)

Final Step : Building Package

I Building packages require going to the command prompt and using commands like R CMD check, R CMD build and R CMD INSTALL.

I In Windows it is Rcmd instead of R CMD.

I All the command prompts must be in the proper directory.

I It can be done from within the R console.

7 / 20

(8)

Final Step : Building Package

I First make sure a package is properly documented by calling document.

I The first argument will be the path to the root folder of the package.

I If the current working directory is similar to the root folder, then no arguments are even needed.

I It is true of all the devtools functions.

I Build all the necessary .Rd files, the NAMESPACE file and the DESCRIPTION file.

(9)

Submitting the package to CRAN

I After submission, CRAN will send you an email and ask you to confirm that the package was uploaded by the maintainer.

I So when you are replying CRAN make sure that the subject line is of the format CRAN Upload: PackageName

PackageVersion.

I Remember that the name of the package is case sensitive.

9 / 20

(10)

Submitting the package to CRAN

I Be careful about the name of the package because it must match with the name of the package in the DESCRIPTION file.

I You can write anything in the body of the message there are no particular guidelines.

(11)

Use of other language

I Sometimes R code is not enough. In that case you should use a compiled language.

I You can use the languages like C, C++, FORTRAN.

I .Fortran is used for calling a function written in FORTRAN.

I .Call is used for calling C and C++ functions.

11 / 20

(12)

I Rcpp package is a great package for integrating C++ code.

I It handles a lot of the scaffolding necessary to make C++

functions which are called from R.

(13)

I A number of tools are necessary for working with C++ code.

I First, you need a proper C++ compiler. In that case it is better to use gcc.

I Linux users have gcc installed.

I Mac users need to install Xcode and might have to manually select g++.

13 / 20

(14)

I It is easy for Windows users to get started.

I RTools provide all necessary development tools including gcc and make.

I The proper version can be downloaded from

http://cran.r-project.org/bin/windows/Rtools/ and installed easily.

(15)

I It installs gcc.

I If you build packages from within R using devtools and RStudio:

then the location of gcc will be determined from the operating system’s registry.

I A LATEX distribution is needed for building package help documents.

15 / 20

(16)

Compiling Packages

I sourceCpp makes ad hoc C++ compilation easy.

I When you are writing C++ function it should be saved in a .cpp file.

I So that it can be sourced using sourceCpp, which

automatically compiles the code and create a new R function with the same name.

I To execute the C++ function., a different strategy is needed for building R packages using C++ code.

(17)

Compiling Packages

I The C++ code is usually put in a .cpp file inside the src folder.

I Any functions will be converted into end user facing R

functions when the package is built using build from devtools.

I Any roxygen2 documentation will be used to document the resulting R function.

I vector add function should be rewritten using roxygen2.

17 / 20

(18)

Compiling Packages

I Rcpp compiles the code and creates a new .R file in the R folder.

I Any functions which are not preceded by // [[Rcpp::export]]

are called from within other C++ functions, but not from R by using .Call.

I To execute C++ functions, a package’s NAMESPACE must contain useDynLib(PackageName).

(19)

Compiling Packages

I This can be done by putting the @useDynLibPackageName tag in any of the roxygen2 blocks.

I In addition if a package uses Rcpp, the DESCRIPTION file must list Rcpp in both the LinkingTo and Depends fields.

I The src folder of the package must contain Makevars and Makevars.win files to help the compilation.

19 / 20

(20)

Conclusion

I Building a package is a great way to make code portable between projects.

I A package if built with R code only requires working functions.

I These working functions should pass the CRAN check using check and proper help files.

I These help files further can be easily built by including roxygen2 documentation and calling document.