[R-pkg-devel] handling documentation build tools
I have some documentation that requires external tools to build. I would like to build the automatically, with requiring either users or repositories to have the tools. What's the best way to accomplish that. Specifically one document is written using the LyX word processor, so the "source" is msep.lyx. To convert that into something useful, a pdf, one must run lyx, which in turn requires latex. I'm looking for recommendations about how to approach this. A purely manual approach would be to place msep.lyx in .Rbuildignore and manually regenerate the pdf if I edit the file. This has 2 drawbacks: first, it does not guarantee that the pdf is consistent with the current source; second, if I want to generate plain text or html versions of the document as well, the manual approach gets more tedious and error prone. Currently I use pkgbuild::build's option to run bootstrap.R to run the lyx->pdf conversion automatically with each build. The script is pretty specific to my build environment, and I think if I uploaded the package CRAN would end up trying to run bootstrap.R, which would fail. Maybe the script should go in tools/? But then it won't run automatically. Maybe the script in tools goes in .Rbuildignore and the bootstrap.R script simply checks if the tools/ script exists and runs it if present. Suggestions? I'm also unsure what directory msep.lyx should go in, though that's a secondary issue. Currently it's in inst/doc, which led to problems with the build system sometimes wiping it out. I've solved that problem. Thanks. Ross [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] handling documentation build tools
Thanks for the pointer. You may have been thrown off by some goofs I made in the intro, which said > I would like to build the automatically, with requiring either users or > repositories to have the tools. The intended meaning, with corrections in **, was > I would like to build the *custom documentation* automatically, with*out* > requiring either users or repositories to have the tools. So I want to build the document only locally, as you suggest, but am not sure how to accomplish that. Regarding the trick, I'm puzzled by what it gains. It seems like a complicated way to get the core pdf copied to inst/doc. Also, my main concern was how to automate production of the "core" pdf, using the language of the blog post. Ross From: Dirk Eddelbuettel Sent: Tuesday, May 21, 2024 2:15 PM To: Boylan, Ross Cc: r-package-devel@r-project.org Subject: Re: [R-pkg-devel] handling documentation build tools !---| This Message Is From an External Sender This message came from outside your organization. |---! As lyx is not listed in 'Writing R Extensions', the one (authorative) manual describing how to build packages for R, I would not assume it to be present on every CRAN machine building packages. Also note that several user recently had to ask here how to deal with less common fonts for style files for (pdf)latex. So I would recommend 'localising' the pdf creation to your own machine, and to ship the resulting pdf. You can have pre-made pdfs as core of a vignette, I trick I quite like to make package building simpler and more robust. See https://urldefense.com/v3/__https://www.r-bloggers.com/2019/01/add-a-static-pdf-vignette-to-an-r-package/__;!!LQC6Cpwp!vcNeLBuZJDE3hWqjhjwi0NVVeEkEHhrSe847H98Eqj9ZEEBspCetgb6g-F7a518JPRd35jL-7xkOlj0$ for details. Cheers, Dirk -- dirk.eddelbuettel.com | @eddelbuettel | e...@debian.org __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
[R-pkg-devel] different build tools
There are at least 4 ways to build a package: 1. R CMD build 2. pkgbuild::build(), which I believe calls 1. 3. devtools::build(), which calls 2. 4. RStudio GUI, which calls 3. I recently discovered these don't all behave the same. Invoking bootstrap.R at the start requires 2 or greater. And invoking 3 directly produced different behavior than 4, apparently because of different defaults for the clean_doc option of 2. Similar remarks apply to R CMD check. I'm puzzled by the plethora of tools and options. In particular I had assumed that if check and build worked in RStudio, I'd get the same results from R CMD. I assume the latter is used on CRAN, and so it would be reasonable to expect the package would build there. Can anyone help me understand what's going on? More specifically, what are the design goals of the different tools. Clearly if devtools::build were the same as pkgbuild:build there would be no reason for the former to exist. Thanks. Ross [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] different build tools
-Original Message- From: Duncan Murdoch Sent: Tuesday, May 28, 2024 3:30 PM To: Boylan, Ross ; r-package-devel@r-project.org Subject: Re: [R-pkg-devel] different build tools On 2024-05-28 6:20 p.m., Boylan, Ross via R-package-devel wrote: > There are at least 4 ways to build a package: > >1. R CMD build >2. pkgbuild::build(), which I believe calls 1. >3. devtools::build(), which calls 2. >4. RStudio GUI, which calls 3. > > I recently discovered these don't all behave the same. Invoking > bootstrap.R at the start requires 2 or greater. What is bootstrap.R? Duncan Murdoch -- Response: It's a script one can enable to run at the start of the build. There is no standard script; it is up to the author(s) to provide it. The devtools::build help says there is a configuration option in DESCRIPTION: Config/build/bootstrap can be set to TRUE to run Rscript bootstrap.R in the source directory prior to running subsequent build steps. I'm using it to build some custom documentation. Furthermore, I put boostrap.R in .Rbuildignore so that package consumers won't try to run software that they may not have. In other words, I'm using it to do some special master-copy-only processing, though I doubt that was the intent of the feature. Ross P.S. Another difference between the RStudio build and R CMD build is that RStudio adds directories to PATH with the additional software it supplies, like pango, which builds require. Plain R CMD build did not have access to them and failed for that reason until I added them to PATH. Alternately I could have done a separate installation of the necessary tools, but that seemed a wasteful complication. __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] different build tools
[Sorry: Outlook doesn't quote messages the "normal" way] -Original Message- From: Simon Urbanek Sent: Tuesday, May 28, 2024 4:10 PM Ross, R CMD build is the only offical way to build a (source) package in R. All other "tools" are just convenience wrappers [] Please note that CRAN has nothing to do with any of the above - a package submitted to CRAN is the resulting package source tar ball which the author created by calling R CMD build - CRAN is not involved in the source package creation, it only requires it to be created with R CMD build for submission. Whether you desire some pre-processing, before you call R CMD build yourself, it's up to you. Cheers, Simon --- Is it required that the package submitted to CRAN have been built with R CMD build rather than some other tool? When you say "CRAN has nothing to do with any of the above [different tools]" it sounds as if one can use anything; but "a package submitted to CRAN is ... created by calling R CMD build" sounds as if that's mandatory. Ross __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
