Folding roxygen(2) into the install_github() workflow

[rpruim]

It would be nice if there were a way to signal to install_github() that some script should be run before installing, or at least that roxygen should be used to create Rd files and NAMESPACE. That way, derived files don't need to be kept in the repository.

[hadley]

How about having a file called devtools-install.r in the root directory of the package? It would be source()d on install.

[rpruim]

Sounds like a good solution to me.

[hadley]

Actually, I think it would have to be devtools-build.r and it would be run prior to build.

[hadley]

No, scratch that, because then that would cause problems when you're working on local projects.

[hadley]

I think my main question is whether this script should run for both and local and remote installs, or just remote. If just remote, it may need a slightly different name.

[hadley]

Or is that better to do in a make file?

[rpruim]

The trouble with a Makefile is that it requires users to know one more thing. It would be nicer if it were an R file. Anyone making an R package will know how an R file works. They may or may not know how to build a sane Makefile. Besides, the things that one is likely to want to do are R-ish (like running roxygen).

But if a Makefile is the simplest way, it will likely solve my problems.

But I suppose this is pretty low priority, since having the Rd files in the repository is not so terrible. (And as a side effect, it reminds you which documentation has changed when you do your commits.)

[hadley]

I think I'm going to close this issue - it's relatively low priority and I think should probably be solved server side with better systems for automated building of R packages.

[krlmlr]

Maintaining those .Rd files in parallel is a real pain, especially when working on repositories that are roxygenized with a not-so-up-to-date version of roxygen2. May I suggest reconsidering this? To trigger this, we could use a mechanism similar to that employed by roxygen2 to indicate if wrapping is enabled:

Devtools: list(pre_build=Rd2roxygen::rab('.'))

or something along these lines.

What's wrong with creating documentation during build/install from src/Makefile? The following seems to work for me:

Rscript -e 'devtools::install_github("krlmlr/R-pkg-template@auto-roxygenize")'

Source: https://github.com/krlmlr/R-pkg-template/tree/auto-roxygenize

(The NAMESPACE and DESCRIPTION files might be an issue, not sure if these get updated. But the .Rd files seem to be generated and installed properly.)

[hadley]

1. I'm not convinced this problem shouldn't be solved by providing built packages from the build system (e.g. travis). Then existing tools take care of making sure the correct versions of build-time dependencies are installed.
2. Can't rely on makefiles because many users won't have make.

[krlmlr]

Thanks for your feedback.

1. In an ideal world, yes. But these services tend to be even more difficult to set up (e.g., private key to the repo to push back to). Also, currently this would work only for GitHub and only for Travis CI.
2. A Windows user who wants to install from source needs Rtools -> Cygwin make, when installing from binary the .Rd files are already generated through R CMD build. For other OSs we can really assume the existence of make, otherwise many other packages that need compilation are not installable either. Could you describe a relevant situation where make is not available?

[hadley]

1. Yes, those tools are a pain currently, but I think that's the right approach to the problem. If, for example, r-forge was actually a distributed R build server, we probably wouldn't be having this conversation.
2. A window user installing a package without compiled code does not currently need Rtools, and so does not have make. Also not sure if make available on the OS X command line without installing the xcode command line tools.

[krlmlr]

1. Perhaps rstudio.com could provide such a service, based on (a fork of) Travis CI?
2. Installing from source requires extra one-time effort from the user. But installing Rtools is very simple, and so I assume is installing xcode on OS X. (Isn't it even required for install_github?) Also, both platforms allow for "binary" packages. (There's nothing like WinBuilder on OS X, is it?)

To sum up the discussion:

• devtools is not the right place to implement roxygenize-before-build
• A CI service would be better for that, but currently there's nothing that would be easy to use
• Roxygenizing via src/Makefile could work but requires further investigation and an installation of Rtools/xcode on Windows/OS X

How to proceed from here to be able to keep the redundant .Rd files out of the Git tree one day?

[yihui]

Although I do not want to mention the possible hack, I think you have a good point there, which is also what I wanted a few years ago (in my early days of using roxygen, I hated the bogus changes in GIT very much). What you can do is to hack the Authors@R field in DESCRIPTION, which will be parsed and evaluated during R CMD build:

Authors@R: if (file.exists('DESCRIPTION') && !file.exists('man')) roxygen2::roxygenize('.');
    person('Joe', 'J', role=c('cre','aut'), email='joe@example.com')

Then roxygenization is done automatically, and you do not need to put man/ in your GIT repository. No need to use Makefile, so no RTools. No CI. No devtools support. It is a pure R solution, but it is just a hack. The more reasonable support should come from R core by allowing some code to be executed before R CMD build. There has been a discussion in r-help (https://stat.ethz.ch/pipermail/r-devel/2013-October/067722.html), where Henrik really had a good point, but Duncan did not seem to get it. Sigh.

[krlmlr]

@yihui: This is really evil. And beautiful. What do you mean by "no devtools support" -- no devtools support needed? This won't appear in the installed DESCRIPTION file, right? Were you able to place such a package on CRAN?

[yihui]

To confess, I used this trick once to hack r-forge.r-project.org because nobody answered me when I requested installing some dependencies. I don't dare using it on CRAN. Crandalf will not be happy seeing this, I guess.

I mean no need to request devtools support. Wherever you can call R CMD build, you can use this trick.

[krlmlr]

@hadley: Technically it's possible to keep .Rd files out of a Git repository, only that install_github doesn't work anymore. Would you review a pull request that allows pre-build actions to be executed by devtools? Perhaps configurable with a Devtools: list(...) field in DESCRIPTION. Once implemented in devtools, these could be adopted later by R CMD build if they turn out to be useful.

[hadley]

@krlmlr Can you please start a new issue? I think the important things to discuss are how to record build time dependencies (version BuildDepends field) and what operations should be baked in.