R devel - Nov 2004 - Questions on package creation

I have some questions about 

   1. nomenclature, 
   2. recommended file locations and 
   3. overall procedure related to creating packages.

To the extent that it matters, examples here relate to Windows XP
R 2.0.1 beta.  

The questions are interspersed and prefaced with ***.

My understanding is that there are actually 6 forms of a package
that one should use in package development:

1. original package.  This refers to the original source files, 
   documentation and other files that the author develops.  
   If source control, e.g. svn, is used then these are the files 
   that are under source control.  They are kept in some arbitrary 
   location on one's disk.  Let us say \usr\mypackage, for example.

*** Is there some standard name for this form of the package?

2. source archive.  This is created from the original package
   like this:

     cd \Program Files\rw2001beta
     bin\R CMD build /usr/mypackage

   which creates, say

     \Program Files\rw2001beta\mypackage_1.0-1.tar.gz

   The source archive is distinct from the original archive since it
   is specific to a version of R and excludes the files referenced
   in \usr\mypackage\.Rbuildignore

*** Is \Program Files\rw2001beta the correct place to put this
   .tar.gz file?

3. source tree.  This is created from the gzipped tar archive in #2
   like this:

     cd \Program Files\rw2001beta
     gzip -d mypackage_1.0-1.tar.gz
     cd src\library
     tar xvf ..\..\mypackage_1.0-1.tar

   and is checked like this:

     cd \Program Files\rw2001beta
     bin\R CMD check mypackage

4. binary archive.  This is created from the source archive in #2
   or the source tree in #3:

      cd \Program Files\rw2001beta
      bin\R CMD build mypackage --binary
    
   which creates \Program Files\rw2001beta\myhpackage_1.0-1.zip

*** Is \Program Files\rw2001beta the correct place to put this?

5. installed package.  This installed by:

     cd \Program Files\rw2001beta
     bin\R CMD install mypackage

  which results in the source package being installed in:
  
     \Program Files\rw2001beta\library\mypackage

  This can alternately be done with the R GUI menu: 

    Packages | Install package(s) from local zip files

6. loaded package.  In R using the command:

     library(mypackage)

   loads the package into R.  This can alternately be done
   using the R GUI menu:

      Packages | Load package

One might initially skip #3 and #4 and just test the package out
in R after #6 and once one is satisfied that it is in good shape
repeat the sequence.

*** Is all the above the correct and recommended sequence?

*** Someone mentioned that --force is important.  How does that 
    fit into all this?  I still have not used it and am not sure
    about it.

Hi,
I mentioned --force
R CMD build --force
is creating the INDEX file automatically. I use it normally.

And in my view in your sequence the point 2. is superfluous in your 
sequence.
You do not need a build neither before check nor INSTALL.

/E


Gabor Grothendieck wrote:
>I have some questions about 
>
>   1. nomenclature, 
>   2. recommended file locations and 
>   3. overall procedure related to creating packages.
>
>To the extent that it matters, examples here relate to Windows XP
>R 2.0.1 beta.  
>
>The questions are interspersed and prefaced with ***.
>
>My understanding is that there are actually 6 forms of a package
>that one should use in package development:
>
>1. original package.  This refers to the original source files, 
>   documentation and other files that the author develops.  
>   If source control, e.g. svn, is used then these are the files 
>   that are under source control.  They are kept in some arbitrary 
>   location on one's disk.  Let us say \usr\mypackage, for example.
>
>*** Is there some standard name for this form of the package?
>
>2. source archive.  This is created from the original package
>   like this:
>
>     cd \Program Files\rw2001beta
>     bin\R CMD build /usr/mypackage
>
>   which creates, say
>
>     \Program Files\rw2001beta\mypackage_1.0-1.tar.gz
>
>   The source archive is distinct from the original archive since it
>   is specific to a version of R and excludes the files referenced
>   in \usr\mypackage\.Rbuildignore
>
>*** Is \Program Files\rw2001beta the correct place to put this
>   .tar.gz file?
>
>3. source tree.  This is created from the gzipped tar archive in #2
>   like this:
>
>     cd \Program Files\rw2001beta
>     gzip -d mypackage_1.0-1.tar.gz
>     cd src\library
>     tar xvf ..\..\mypackage_1.0-1.tar
>
>   and is checked like this:
>
>     cd \Program Files\rw2001beta
>     bin\R CMD check mypackage
>
>4. binary archive.  This is created from the source archive in #2
>   or the source tree in #3:
>
>      cd \Program Files\rw2001beta
>      bin\R CMD build mypackage --binary
>    
>   which creates \Program Files\rw2001beta\myhpackage_1.0-1.zip
>
>*** Is \Program Files\rw2001beta the correct place to put this?
>
>5. installed package.  This installed by:
>
>     cd \Program Files\rw2001beta
>     bin\R CMD install mypackage
>
>  which results in the source package being installed in:
>  
>     \Program Files\rw2001beta\library\mypackage
>
>  This can alternately be done with the R GUI menu: 
>
>    Packages | Install package(s) from local zip files
>
>6. loaded package.  In R using the command:
>
>     library(mypackage)
>
>   loads the package into R.  This can alternately be done
>   using the R GUI menu:
>
>      Packages | Load package
>
>One might initially skip #3 and #4 and just test the package out
>in R after #6 and once one is satisfied that it is in good shape
>repeat the sequence.
>
>*** Is all the above the correct and recommended sequence?
>
>*** Someone mentioned that --force is important.  How does that 
>    fit into all this?  I still have not used it and am not sure
>    about it.
>
>______________________________________________
>R-devel@stat.math.ethz.ch mailing list
>https://stat.ethz.ch/mailman/listinfo/r-devel
>
>  
>

-- 
Dipl. bio-chem. Witold Eryk Wolski
MPI-Moleculare Genetic
Ihnestrasse 63-73 14195 Berlin
tel: 0049-30-83875219                 __("<    _
http://www.molgen.mpg.de/~wolski      \__/    'v'
http://r4proteomics.sourceforge.net    ||    /   \
mail: witek96@users.sourceforge.net    ^^     m m
      wolski@molgen.mpg.de

Gabor Grothendieck wrote:
> I have some questions about 
> 
>    1. nomenclature, 
>    2. recommended file locations and 
>    3. overall procedure related to creating packages.
> 
> To the extent that it matters, examples here relate to Windows XP
> R 2.0.1 beta.  
> 
> The questions are interspersed and prefaced with ***.
> 
> My understanding is that there are actually 6 forms of a package
> that one should use in package development:
> 
> 1. original package.  This refers to the original source files, 
>    documentation and other files that the author develops.  
>    If source control, e.g. svn, is used then these are the files 
>    that are under source control.  They are kept in some arbitrary 
>    location on one's disk.  Let us say \usr\mypackage, for example.
> 
> *** Is there some standard name for this form of the package?
> 
> 2. source archive.  This is created from the original package
>    like this:
> 
>      cd \Program Files\rw2001beta
>      bin\R CMD build /usr/mypackage
You won't need to cd to anything.

>    which creates, say
> 
>      \Program Files\rw2001beta\mypackage_1.0-1.tar.gz
> 
>    The source archive is distinct from the original archive since it
>    is specific to a version of R and excludes the files referenced
>    in \usr\mypackage\.Rbuildignore
and others, e.g., .cvs files.

> *** Is \Program Files\rw2001beta the correct place to put this
>    .tar.gz file?

It's arbitrary where to save it, I would not save it in the R directory, 
though.

> 3. source tree.  This is created from the gzipped tar archive in #2
>    like this:
> 
>      cd \Program Files\rw2001beta
>      gzip -d mypackage_1.0-1.tar.gz
>      cd src\library
>      tar xvf ..\..\mypackage_1.0-1.tar
> 
>    and is checked like this:
> 
>      cd \Program Files\rw2001beta
>      bin\R CMD check mypackage
> 
> 4. binary archive.  This is created from the source archive in #2
>    or the source tree in #3:
> 
>       cd \Program Files\rw2001beta
>       bin\R CMD build mypackage --binary
>
or join this with step 5 using
R CMD INSTALL --build mypackage
>    which creates \Program Files\rw2001beta\myhpackage_1.0-1.zip
> 
> *** Is \Program Files\rw2001beta the correct place to put this?

... also arbitrary (as above) ...

> 5. installed package.  This installed by:
> 
>      cd \Program Files\rw2001beta
>      bin\R CMD install mypackage
> 
>   which results in the source package being installed in:
>   
>      \Program Files\rw2001beta\library\mypackage
> 
>   This can alternately be done with the R GUI menu: 
> 
>     Packages | Install package(s) from local zip files
> 
> 6. loaded package.  In R using the command:
> 
>      library(mypackage)
> 
>    loads the package into R.  This can alternately be done
>    using the R GUI menu:
> 
>       Packages | Load package
> 
> One might initially skip #3 and #4 and just test the package out
> in R after #6 and once one is satisfied that it is in good shape
> repeat the sequence.
> 
> *** Is all the above the correct and recommended sequence?
As always: It depends. Nothing of the above is completely wrong.


> *** Someone mentioned that --force is important.  How does that 
>     fit into all this?  I still have not used it and am not sure
>     about it.
It is used to overwrite the INDEX file.

Uwe Ligges
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

Gabor,

Here are my takes on these:

1: Not that I know of.  Only the package developer(s) see the code this way,
and is really not different from 3.  (A developer would not need 3, as R CMD
check can be done with 1.)

2 & 4: As Uwe said, the location is `whereever you like'.  You would
create
them only for distribution (i.e., installation on other machines), so it
doesn't matter where it put them.  They only exist temporarily on the
developer's machine (assuming the source is version controlled via other
means), as only a user wanting to install the package would need the archive
forms.

Here's the sequence I use:

Start with a source tree for the package somewhere.

Testing/checking:

Run R CMD INSTALL -l mytest mypkg (making sure you create the `mytest'
directory first).  This installs the package in the `mytest' directory.  If
the install is not successful, make necessary changes.  If successful, start
up R (from the command line) and do library(mypkg, lib.loc="mytest")
and run
some tests (e.g., example() for functions in the package).

After making sure the installed package looks good, run R CMD check mypkg.
Make changes to correct errors and warnings.

After successful check, run R CMD build --force mypkg to generate the source
tarball and update the INDEX file.  (The --force is only needed if you
add/remove/change help page topics since the last build.)

Run R CMD build --binary mypkg if you need to distribute the package in
binary form.

HTH,
Andy
> From: Gabor Grothendieck
> 
> I have some questions about 
> 
>    1. nomenclature, 
>    2. recommended file locations and 
>    3. overall procedure related to creating packages.
> 
> To the extent that it matters, examples here relate to Windows XP
> R 2.0.1 beta.  
> 
> The questions are interspersed and prefaced with ***.
> 
> My understanding is that there are actually 6 forms of a package
> that one should use in package development:
> 
> 1. original package.  This refers to the original source files, 
>    documentation and other files that the author develops.  
>    If source control, e.g. svn, is used then these are the files 
>    that are under source control.  They are kept in some arbitrary 
>    location on one's disk.  Let us say \usr\mypackage, for example.
> 
> *** Is there some standard name for this form of the package?
> 
> 2. source archive.  This is created from the original package
>    like this:
> 
>      cd \Program Files\rw2001beta
>      bin\R CMD build /usr/mypackage
> 
>    which creates, say
> 
>      \Program Files\rw2001beta\mypackage_1.0-1.tar.gz
> 
>    The source archive is distinct from the original archive since it
>    is specific to a version of R and excludes the files referenced
>    in \usr\mypackage\.Rbuildignore
> 
> *** Is \Program Files\rw2001beta the correct place to put this
>    .tar.gz file?
> 
> 3. source tree.  This is created from the gzipped tar archive in #2
>    like this:
> 
>      cd \Program Files\rw2001beta
>      gzip -d mypackage_1.0-1.tar.gz
>      cd src\library
>      tar xvf ..\..\mypackage_1.0-1.tar
> 
>    and is checked like this:
> 
>      cd \Program Files\rw2001beta
>      bin\R CMD check mypackage
> 
> 4. binary archive.  This is created from the source archive in #2
>    or the source tree in #3:
> 
>       cd \Program Files\rw2001beta
>       bin\R CMD build mypackage --binary
>     
>    which creates \Program Files\rw2001beta\myhpackage_1.0-1.zip
> 
> *** Is \Program Files\rw2001beta the correct place to put this?
> 
> 5. installed package.  This installed by:
> 
>      cd \Program Files\rw2001beta
>      bin\R CMD install mypackage
> 
>   which results in the source package being installed in:
>   
>      \Program Files\rw2001beta\library\mypackage
> 
>   This can alternately be done with the R GUI menu: 
> 
>     Packages | Install package(s) from local zip files
> 
> 6. loaded package.  In R using the command:
> 
>      library(mypackage)
> 
>    loads the package into R.  This can alternately be done
>    using the R GUI menu:
> 
>       Packages | Load package
> 
> One might initially skip #3 and #4 and just test the package out
> in R after #6 and once one is satisfied that it is in good shape
> repeat the sequence.
> 
> *** Is all the above the correct and recommended sequence?
> 
> *** Someone mentioned that --force is important.  How does that 
>     fit into all this?  I still have not used it and am not sure
>     about it.
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> 
>

I write most of the code in randomForest in Windows, and move to Linux when
I need to debug compiled code.  On my WinXPPro laptop, I have a directory
c:/home/R-packages/RF.  That's where the randomForest source tree lives.
When I'm ready to do some test, I would do (on the command line, in
c:/home/R-packages/RF)

  mkdir test
  R CMD INSTALL -l test randomForest

If the install is OK, I then start up Rterm or Rgui from the directory and
do

  library(randomForest, lib.loc="test")

and play with the package a bit to make sure it looks OK.  Then at the
system command line,

  R CMD check randomForest

If that goes well, I'd do:

  R CMD build --force randomForest
  R CMD build --binary randomForest

and move the .tar.gz and .zip archives to whereever I want them.  Before I
use subversion for version control, I would simply stash away the .tar.gz in
c:/home/R-packages/rf-pkg, which holds the tarball of various versions of
the package.  Not particularly efficient, obviously.

HTH,
Andy
  
> From: Gabor Grothendieck
> 
> Thanks.  One thing I would like clarified is the various locations
> and what is relative to where.
> 
> If you could add to the example where we are in terms of an example
> absolute path and where the various directories wind up also in
> terms of example absolute paths it would clear up a lot.
> 
> Liaw, Andy <andy_liaw <at> merck.com> writes:
> 
> : 
> : Gabor,
> : 
> : Here are my takes on these:
> : 
> : 1: Not that I know of.  Only the package developer(s) see 
> the code this way,
> : and is really not different from 3.  (A developer would not 
> need 3, as R CMD
> : check can be done with 1.)
> : 
> : 2 & 4: As Uwe said, the location is `whereever you like'.  
> You would create
> : them only for distribution (i.e., installation on other 
> machines), so it
> : doesn't matter where it put them.  They only exist 
> temporarily on the
> : developer's machine (assuming the source is version 
> controlled via other
> : means), as only a user wanting to install the package would 
> need the archive
> : forms.
> : 
> : Here's the sequence I use:
> : 
> : Start with a source tree for the package somewhere.
> : 
> : Testing/checking:
> : 
> : Run R CMD INSTALL -l mytest mypkg (making sure you create 
> the `mytest'
> : directory first).  This installs the package in the 
> `mytest' directory.  If
> : the install is not successful, make necessary changes.  If 
> successful, start
> : up R (from the command line) and do library(mypkg, 
> lib.loc="mytest") and run
> : some tests (e.g., example() for functions in the package).
> : 
> : After making sure the installed package looks good, run R 
> CMD check mypkg.
> : Make changes to correct errors and warnings.
> : 
> : After successful check, run R CMD build --force mypkg to 
> generate the source
> : tarball and update the INDEX file.  (The --force is only 
> needed if you
> : add/remove/change help page topics since the last build.)
> : 
> : Run R CMD build --binary mypkg if you need to distribute 
> the package in
> : binary form.
> : 
> : HTH,
> : Andy
> : 
> : > From: Gabor Grothendieck
> : > 
> : > I have some questions about 
> : > 
> : >    1. nomenclature, 
> : >    2. recommended file locations and 
> : >    3. overall procedure related to creating packages.
> : > 
> : > To the extent that it matters, examples here relate to Windows XP
> : > R 2.0.1 beta.  
> : > 
> : > The questions are interspersed and prefaced with ***.
> : > 
> : > My understanding is that there are actually 6 forms of a package
> : > that one should use in package development:
> : > 
> : > 1. original package.  This refers to the original source files, 
> : >    documentation and other files that the author develops.  
> : >    If source control, e.g. svn, is used then these are the files 
> : >    that are under source control.  They are kept in some 
> arbitrary 
> : >    location on one's disk.  Let us say \usr\mypackage, 
> for example.
> : > 
> : > *** Is there some standard name for this form of the package?
> : > 
> : > 2. source archive.  This is created from the original package
> : >    like this:
> : > 
> : >      cd \Program Files\rw2001beta
> : >      bin\R CMD build /usr/mypackage
> : > 
> : >    which creates, say
> : > 
> : >      \Program Files\rw2001beta\mypackage_1.0-1.tar.gz
> : > 
> : >    The source archive is distinct from the original 
> archive since it
> : >    is specific to a version of R and excludes the files referenced
> : >    in \usr\mypackage\.Rbuildignore
> : > 
> : > *** Is \Program Files\rw2001beta the correct place to put this
> : >    .tar.gz file?
> : > 
> : > 3. source tree.  This is created from the gzipped tar 
> archive in #2
> : >    like this:
> : > 
> : >      cd \Program Files\rw2001beta
> : >      gzip -d mypackage_1.0-1.tar.gz
> : >      cd src\library
> : >      tar xvf ..\..\mypackage_1.0-1.tar
> : > 
> : >    and is checked like this:
> : > 
> : >      cd \Program Files\rw2001beta
> : >      bin\R CMD check mypackage
> : > 
> : > 4. binary archive.  This is created from the source archive in #2
> : >    or the source tree in #3:
> : > 
> : >       cd \Program Files\rw2001beta
> : >       bin\R CMD build mypackage --binary
> : >     
> : >    which creates \Program Files\rw2001beta\myhpackage_1.0-1.zip
> : > 
> : > *** Is \Program Files\rw2001beta the correct place to put this?
> : > 
> : > 5. installed package.  This installed by:
> : > 
> : >      cd \Program Files\rw2001beta
> : >      bin\R CMD install mypackage
> : > 
> : >   which results in the source package being installed in:
> : >   
> : >      \Program Files\rw2001beta\library\mypackage
> : > 
> : >   This can alternately be done with the R GUI menu: 
> : > 
> : >     Packages | Install package(s) from local zip files
> : > 
> : > 6. loaded package.  In R using the command:
> : > 
> : >      library(mypackage)
> : > 
> : >    loads the package into R.  This can alternately be done
> : >    using the R GUI menu:
> : > 
> : >       Packages | Load package
> : > 
> : > One might initially skip #3 and #4 and just test the package out
> : > in R after #6 and once one is satisfied that it is in good shape
> : > repeat the sequence.
> : > 
> : > *** Is all the above the correct and recommended sequence?
> : > 
> : > *** Someone mentioned that --force is important.  How does that 
> : >     fit into all this?  I still have not used it and am not sure
> : >     about it.
> : > 
> : > ______________________________________________
> : > R-devel <at> stat.math.ethz.ch mailing list
> : > https://stat.ethz.ch/mailman/listinfo/r-devel
> : > 
> : >
> : 
> : ______________________________________________
> : R-devel <at> stat.math.ethz.ch mailing list
> : https://stat.ethz.ch/mailman/listinfo/r-devel
> : 
> :
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
> 
>