[Rd] Makefiles and other customization

[Kurt Hornik]

>>>>> Ross Boylan writes:

> Writing R Extensions mentions that a package developer can provide a
> Makefile, but gives very little information about what should be in it.
> It says there must be a clean target, and later on there's mention of 
>      $(SHLIB): $(OBJECTS)
>              $(SHLIB_LINK) -o $@ $(OBJECTS) $(ALL_LIBS)
> (in the F95 discussion).

> What should a Makefile provide, and what can it assume?  In other
> words, what variables and environment setup should have been done?  My
> guess is that all the R boilerplate for Makefiles will have been read
> before the Makefile I provide.  It appears from the F95 example that
> the Makefile has to get the names of the files it needs itself.

> I suspect this is not documented more fully because of the extreme
> difficulty of writing a portable Makefile.  However, I already have a
> "Makefile.full", so called to avoid having R use it.  Makefile.full
> does lots of stuff, so portability is already compromised.  I'm
> thinking it might be more direct to provide "Makefile," since I'm now
> trying to alter what R CMD build does.

> I posted a related question on r-help, before I realized this kind of
> issue is more appropriate for this list.  The question I asked there
> was whether it would be reasonable to do my own tar of the files I
> wanted to distribute in place of using R CMD build.  I'm also
> interested in knowing about that.
> https://stat.ethz.ch/pipermail/r-help/2005-November/081758.html
> (though the thread has so far been on a tangential issue).

> Here is that first post, if you want more background:
> ---------------------------------------------------------------
> I've made a package for which R CMD build isn't producing very
> satisfactory results.  I'll get to the details in a moment.

> I wonder if it would make sense to have my own makefiles (which
> already exist and are doing quite a lot) produce the .tar.gz file
> ordinarily produced by R CMD build.  As far as I can tell, R CMD build
> basically tars up of the project directory after running some checks.
> I could run R CMD check separately.

> There are two main problems with the results of R CMD build.  First,
> it has lots of files that I don't want included (the input files used
> to generate configure, miscellaneous garbage, other stuff not suitable
> for distribution).  Second, I have data files as both "data.gz" and
> "data".  R puts "data" into the .tar.gz file and sensibly ignores the
> .gz file.  Unfortunately, my makefiles assume the existence of the
> "data.gz" files, and so may have trouble after the .tar.gz is unpacked
> and there are no "data.gz" files.

> My bias would ordinarily be to piggy back on the R build system as
> much as possible.  In principle, this could get me extra features
> (binary builds, MS Windows builds) and it would track the things R
> build does beyond tarring files.  But in this case using the R build
> system seems quite ugly.  I could in principle use .Rbuildignore,
> probably generated dynamically, to exclude files.  That doesn't solve
> the 2nd problem (data.gz becomes data).

> So does the alternative of doing the tar'ing myself make sense?

> Is there another option that could hook into the R CMD build process
> more deeply than the use of .Rbuildignore?

> I suppose another option would be to do a clean checkout of the sources
> for my package, run a special makefile target that would create the
> necessary files and delete all unwanted files, and then do a regular R
> CMD build.  This might still have trouble with "data.gz".
> --------------------------------------------------------------

I would typically advocate against bypassing the standard tool-chain.  R
CMD build will continue being enhanced, e.g. by adding more metadata
which certify the authenticity of the toolchain and/or the builder.  Of
course, all this is open source, and one can piggyback on the sources,
but one of the great successes of R and related projects is the fact
that there is a highly standardized way of managing extensions to the
base system.

Re hooks, in addition to .Rbuildignore there is a "cleanup" (before
packaging) mechanism, see sub cleanup_pkg in the build sources.  This is
what runs make clean in the src subdir, and under Unix also a cleanup
shell script in the top level package source directory (and we could in
principle add a cleanup.win mechanism).

I am not sure about the data.gz issue: perhaps you can send me a sample
package to that I can investigate.

-k