Skip to content

Latest commit

 

History

History
81 lines (54 loc) · 4.56 KB

MAINTENANCE.md

File metadata and controls

81 lines (54 loc) · 4.56 KB
Raw

Current state

The state of cpp11 is pretty stable, it seems to have the features we need for most of our projects using C++.

Known outstanding issues

Running the cpp11test tests

Most of the test suite is in a sub-package, cpp11test. Probably the best way to run these tests is to install the development version of cpp11 and then run devtools::test() to run the cpp11test test suite.

If tests failures occur the output from Catch isn't always easy to interpret. I have a branch of testthat https://github.com/jimhester/testthat/tree/catch-detailed-output that should make things easier to understand. I contributed those changes to the main testthat, but something changed after merging the more detailed output was lost, I unfortunately never had the time to track down the cause and fix it.

In addition getting a debugger to catch when errors happen can be fiddly when running the cpp11test tests, something about the way that Catch redirects stderr / stdout interacts with the debugger.

The GitHub Actions workflow has some additional logic to handle running the cpp11 tests

cpp11/.github/workflows/R-CMD-check.yaml

Lines 95 to 102 in fd8ef97

- name: Install cpp11 and cpp11test
if: matrix.config.custom != 'no-cpp11test'
run: |
options(warn = 2)
install.packages(".", repos = NULL, type = "source")
pak::local_install_dev_deps("cpp11test")
install.packages("cpp11test", repos = NULL, INSTALL_opts = "--install-tests", type = "source")
shell: Rscript {0}
,

cpp11/.github/workflows/R-CMD-check.yaml

Lines 117 to 124 in fd8ef97

- name: Run cpp11test tests
if: matrix.config.custom != 'no-cpp11test'
run: |
setwd("cpp11test/tests")
library(testthat)
library(cpp11test)
test_check("cpp11test", reporter = "progress")
shell: Rscript {0}
.

False positive URL checks for git repositories in the vignettes

If you run urlchecker::url_check() on the repo you will see the following false positives.

! Warning: vignettes/motivations.Rmd:363:11 Moved
git clone https://github.com/r-lib/cpp11.git
          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
          https://github.com/r-lib/cpp11
! Warning: vignettes/motivations.Rmd:354:11 Moved
git clone https://github.com/RcppCore/Rcpp.git
          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
          https://github.com/RcppCore/Rcpp
>

These only happen with the urlchecker package, they can be safely ignored and the real CRAN checks will not show them.

Ensure you use Sys.setenv("CPP11_EVAL" = "true"); devtools::submit_cran() when submitting.

If you forget to set CPP_EVAL = "true" then the vignette chunks will not run properly and the vignettes will not be rendered properly.

Regenerating benchmark objects used in motivations.Rmd

If you need to regenerate the benchmark objects (RDS objects) utilized in motivations.Rmd, then you should set Sys.setenv("CPP11TEST_SHOULD_RUN_BENCHMARKS" = "TRUE") before running the Rmd. You'll also need to make sure that cpp11test is actually installed. See cpp11test:::should_run_benchmarks() for more.

Usage with clangd

Since cpp11 is header only, if you use clangd you'll have a bit of an issue because tools like bear and pkgload won't know how to generate the compile_commands.json file. Instead, you can create it manually with something like this, which seems to work well. Note that the paths are specific to your computer.

[
    {
        "command": "g++ -std=gnu++11 -I\"/Users/davis/files/r/packages/cpp11/inst/include\" -I\"/Library/Frameworks/R.framework/Resources/include\" -I\"/Users/davis/Library/R/arm64/4.4/library/Rcpp/include\" -I\"/Users/davis/Library/R/arm64/4.4/library/testthat/include\" -I\"/opt/homebrew/include\" -Wall -pedantic",
        "file": "R.hpp",
        "directory": "/Users/davis/files/r/packages/cpp11/inst/include/cpp11"
    }
]

Key notes:

  • Only doing this for R.hpp seems to be enough. I imagine this could be any of the header files, but it is reasonable to pick the "root" one that pretty much all others include.
  • Using -std=gnu++11 to keep us honest about only C++11 features.
  • Using -I\"/Library/Frameworks/R.framework/Resources/include\" for access to the R headers.
  • Using -I\"/Users/davis/files/r/packages/cpp11/inst/include\" as a "self include", which seems to be the key to the whole thing.

If you are modifying any tests or benchmarks, you also need:

  • -I\"/Users/davis/Library/R/arm64/4.4/library/Rcpp/include\" for Rcpp headers.
  • -I\"/Users/davis/Library/R/arm64/4.4/library/testthat/include\" for testthat headers related to Catch tests.

Note that this is specific to a path on your machine and the R version you are currently working with.

Future directions

Some work could be spent in smoothing out the cpp_source() / knitr chunk experience. Our main focus and use cases were in R packages, so that usage is more tested. Because we don't typically use cpp11 in non package contexts those use cases may not be as nice.

For similar reasons the matrix support might be somewhat lacking, as the majority of our use cases do not deal with numeric matrices.