Step 10. Build

The last step in our process will cover how you build a package. You have two options here. You can build for CRAN or you can just do a locale build for yourself and other windows users.  I will cover the build for CRAN as that is more detailed and then show you how to build for your local machine. Its not a huge difference. When you build for CRAN you  build and check. This is to insure that you pass all the CRAN tests. The output when you are done is a  “tar.gz” file which you upload to CRAN. Then the build process is repeated and  your source is used to build a OSX  binary and a windows binary. The windows binaries are in zip files.  My work flow goes like this. I build EVRYTHING as if I am building for CRAN. That means I write all documents and I pass all checks. Then I build again for windows and produce a ‘zip’ binary.  In short I do the following

1.  R CMD build mypkg   ( generates tar.gz for cran)

2. R CMD check mypkg_1.o.tar.gz

3  R CMD INSTALL –build mypkg   ( gets me a local windows binary   zip file )

But lets walk through that step by step.

PART ONE:  Building for CRAN.

If you followed all the steps you should have all the files you need in a “mypkg” directory below TestPackage. Issue the following command

C:\Users\steve\Documents\TestPackage> R CMD build mypkg

You should see the following:

The build command has created a file called  mypkg_1.0.tar.gz.  That is the file  we would upload to CRAN. They would use that file to create the binaries for windows and OSX.

Before we submit to CRAN however we have to  “check” the package. At the prompt enter ” R CMD check mypkg_1.0.tar.gz

When you do that you will see the following:

Look carefully and you will see that I have generated one “NOTE”. When you run check you can generate NOTES, warnings, and errors. You should fix these before submitting to CRAN. In fact you have to fix all warnings and errors and most Notes.  The note I generated here can be fixed easily by editing the  Rd files ( the package description and description file so that we use GPL-2 as opposed to GPL 2).

Now, there is one last detail. The “check” command has various flags. If you want to see the flags type  R CMD check –help.  If you do that you will see that we should run “check” with the following flag:  R CMD check –as-cran mypkg.    This check will look at one very important thing.  Check out the screen

If you read through that you will see that  “check” has gone out and looked at CRAN to see if my package is a  new package or not. And its generated a NOTE telling me that I am a new submission. That’s important because of the rules you have to follow when you submit: Those rules are found here. PLEASE REVIEW THEM. Pay careful attention to the submission guidelines, for example  “For a new submission, confirm in your email that you have read and agree to these policies. (This includes new versions of previously archived packages, and the first submission as the new maintainer for a package.)”   If you submit a new package without this email ( AS I have ) you  WILL get a  WELL DESERVED nastygram telling you to follow submission policies. Also, don’t do boneheaded things like submitting multiple versions before the first gets posted.  In my excitement I once posted version 1.4, then a few hours later had another version, 1.5 and then a third 1.6.  CRAN doesn’t like that and you will be informed.

PART TWO.

For part two lets suppose that you want to build the windows binary or the “zip” file and then you want to install it on your machine. For this you can just issue the following command:  “R CMD INSTALL –binary mypkg

Do that and you will have a  “zip” version. Then you switch to R Studio, select  “Packages”. Then select ‘install packages’. Then install from local zip archive. Load the library  library(mypkg) and you are good to go.

So shutdown R, restart and load the package library. Then you can   enter ?f  to get help on the “f” function

And you are done. There are a lot more details covered in the documentation. But this should help you get started making packages, simple packages,  on Windows.

You can explore various options with the R  commands  by doing   R CMD INSTALL –help. this works for any of the commands

Finally before you submit your package to CRAN read  the policies. When you submit a package for the first time there are some steps you have to take in your submission email to CRAN.

  1. Oleg M
    December 18, 2011 at 7:14 AM

    With the new version of Rtools (2.15) I was not able to use -binary option. However, the tar.gz format worked just as well (when I installed it using R CMD INSTALL)

    • Steven Mosher
      December 18, 2011 at 8:24 AM

      Thanks,

      I’m in the middle of some projects and have not been able to up get all my old R stuff up to date

  2. Sy
    February 10, 2012 at 10:59 PM

    thanks for the detailed explanation. this is a whole lot better than the R documentation (in trying to find an answer to a question, you end up having ten more questions)
    I’m still not clear on a few things
    1)What is the purpose/role of the PATH variables? i.e. would your ‘mypkg’ example not have worked if I didn’t install the tools listed in step 4 and then edit the PATH
    2)What is lazy loading?

    fyi, i dont have a c:\Rtools\MinGW\bin…. I have c:\Rtools\gcc-4.6.3\bin… I believe this is part of the new Rtools 2.15

    • Chen
      April 6, 2012 at 8:49 PM

      I encountered the same problem of not having the c:\Rtools\MinGW\bin folder. And when I issued the R CMD SHLIB xxx.c command nothing happens. The DLL was not built.

  3. steven mosher
    February 11, 2012 at 6:08 AM

    the path variable tells the command process where to look for the tools.
    so when open a cosole and enter commands the commnd processor knows to look in all the places in the path for the apps that process the commands

  4. March 7, 2012 at 7:09 AM

    First, I just wanted to say thank you for posting this. It this is much better than any other Windows explanation I’ve found online. Thanks for taking the time to put it together!

    Re: tar.gz files
    This is a “tarball”. For R, this is typically a package’s source saved as a compressed file. Each package source on CRAN can be downloaded as a tar.gz file, which can be unzipped using the untar function in R (helpful info if other software to do so isn’t handy). Tarballs can also be installed directly in R, e.g. install.packages(“path/to/mypkg_1.0.tar.gz”, repos=NULL, type=”source”)

    • Steven Mosher
      March 7, 2012 at 7:12 AM

      thanks spread the word.

  5. Berry
    October 5, 2012 at 2:18 PM

    Hi! Thanks a lot! This was very helfpul! This guy here (http://robjhyndman.com/researchtips/building-r-packages-for-windows/) suggests the last steps in the order INSTALL –build, then check, then build. Does the order matter?

    • Steven Mosher
      October 5, 2012 at 9:31 PM

      I need to update this since they deprecated the -binary.. The order I do it in is

      Build, check, install. although I think you can do install first. The R documentation is very terse and not really suitable for beginners.

  6. Berry
    October 5, 2012 at 6:22 PM

    Just in case anybody else is installing packages from disc for the first time (took me forever to find out how to do it.):

    install.packages(“S:/……/BerryFunctions_1.0.tar.gz”, repos=NULL, type=”source”)
    # replace …… with your path

    library(BerryFunctions) # as usual

    • Steven Mosher
      October 7, 2012 at 2:29 AM

      At some point I should probably write a longer piece on writing packages in R. There are a bunch of little things that are not documented very well or documented in out of the way places

  7. November 25, 2012 at 5:34 AM

    to have a .zip you have to use “Rcmd INSTALL –build mypkg”

    • Steven Mosher
      November 25, 2012 at 6:34 AM

      Ya I need to redo this whole page rather than try to handle it with strike throughs.
      That’s probably going to get done tommorrow

  8. Vincent van Hees
    May 10, 2013 at 3:52 PM

    Thanks a lot for posting this explanation. I have gone through all your steps and encounter the following problem when building my package.

    Q:\>R CMD build Q:/scripts/GGIR
    * checking for file ‘Q:/scripts/GGIR/DESCRIPTION’ …Error : file ‘Q:
    /scripts/GGIR/DESCRIPTION’ is not in valid DCF format
    EXISTS but not correct format

    Does this indicate that something is wrong with how i filled in the description file? or is it more likely that something went wrong in the installation of the tools? I have been searching on forums for further clarification about DCF format errors, but no luck. The contents of my description file is as follows:

    Package: GGIR
    Type: Package
    Title: Analysis of Genea or Geneactive accelerometer data
    Version: 1.0
    Date: 2013-05-09
    Author: Vincent T van Hees
    Maintainer: Vincent T van Hees
    Description: The package was develop to process data collected with Genea and
    Geneactive accelerometers when applied for the assessment of human daily physical activity.
    License: LGPL (>= 2.0, < 3)
    Imports: stats, utils, grpahics, grDevices, R(2.10.1), GENEAread, MASS, signal, seewave, matlab, bitops, mmap
    LazyLoad: yes

    the DESCRIPTION file has no extension, file type = file

    • Steven Mosher
      May 11, 2013 at 2:10 AM

      It sounds like you have a bad format. Sometimes you’ll get non printing ascii characters in a file that will be tough to find and remove.

      Try recreating the description file ( no extension) and rebuilding.

      If that doesnt work, then submit a question to R dev sig group

  9. Vincent van Hees
    May 10, 2013 at 3:56 PM

    …sorry, always happens…problem detected just after posting a question. Field names apparently need to be kept on one line and not split up over different lines

  10. September 6, 2013 at 6:08 PM

    Steven, so helpful, worked like a charm. Thanks so much for taking the time to post this information.

  11. September 12, 2013 at 6:36 AM

    オリス 腕時計 店舗 http://www.watchsimpossi.com/

  12. Jose
    October 1, 2013 at 7:39 AM

    This is a great start to understand the basics on creating a package. Very clear and practical. Well done.

  13. June 8, 2014 at 2:17 AM

    Hi Steven,
    Thank you for the post. It is indeed very helpful. I have a question if you could possibly address. My R package depends on a different package which can’t be installed directly from CRAN library but rather from a web link as follows: source(“http://bioconductor.org/biocLite.R”)
    biocLite(“Packagename”)
    library(Packagename)

    When I run the R CMD check, I get an error message indicating the package name was not found. I tried including it in Depends: within the descriptive file but it did not work. Could you possibly help me in this regards ?

  1. June 9, 2011 at 12:21 AM

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 36 other followers

%d bloggers like this: