Expand libraries vignette with PACKAGE_types.h (#1355)

* Expand libraries vignette with PACKAGE_types.h * Correct missing word spotted by @Enchufa2
RcppCore · Jan 26, 2025 · 7ecadc3 · 7ecadc3
1 parent 55a4f01
commit 7ecadc3
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 9 deletions.
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,9 @@
+2025-01-25  Dirk Eddelbuettel  <[email protected]>
+
+	* vignettes/rmd/Rcpp-libraries.Rdm: Add mention of PACKAGE_types.h
+	* vignettes/rmd/Rcpp.bib: Add AsioHeaders
+	* inst/bib/Rcpp.bib: Idem
+
 2025-01-18  Ben Bolker  <[email protected]>
 
 	* inst/NEWS.Rd: fix trivial typos in NEWS file

diff --git a/inst/bib/Rcpp.bib b/inst/bib/Rcpp.bib
@@ -80,6 +80,14 @@ @Manual{CRAN:anytime
   url =		 CRAN # "package=anytime"
 }
 
+@Manual{CRAN:AsioHeaders,
+  title =        {'Asio' C++ Header Files},
+  author =       {Dirk Eddelbuettel},
+  year =         {2024},
+  note =         {R package version 1.22.1},
+  url =		 CRAN # "package=AsioHeaders"
+}
+
 @Manual{CRAN:BH,
   title =        {BH: Boost C++ Header Files},
   author =       {Dirk Eddelbuettel and John W. Emerson and Michael

diff --git a/vignettes/rmd/Rcpp-libraries.Rmd b/vignettes/rmd/Rcpp-libraries.Rmd
@@ -154,15 +154,24 @@ it.
 
 Given a basic package with C++ support, we can now turn to integrating the external
 package.  This complexity of this step can, as alluded to earlier, vary from very easy to
-very complex.  Simple cases include just depending on library headers which can either
-be copied to the package, or be provided by another package such as \pkg{BH}
-\citep{CRAN:BH}. It may also be a dependency on a fairly standard library available on
-most if not all systems.  The graphics formats bmp, jpeg or png may be example; text
-formats like JSON or XML are another.  One difficulty, though, may be that _run-time_
-support does not always guarantee _compile-time_ support. In these cases, a `-dev` or
-`-devel` package may need to be installed.
-
-In the concrete case of Corels, we
+very complex.  Simple cases include just depending on library headers which can either be
+copied to the package, or be provided by another package such as \pkg{BH} \citep{CRAN:BH}
+or \pkg{AsioHeaders} \citep{CRAN:AsioHeaders} or many other examples.
+
+One aspect worth noting is that if you include a type in your function interface it will
+also be part of the generated \code{RcppExports.cpp}. In this case adding a file
+\code{PACKAGE\_types.h} (where \code{PACKAGE} is to be replaced with the name of your
+package) containing the required \code{\#include} statement for the type(s) will permit
+compilation; see the 'Rcpp Attributes' vignette for details \citep{CRAN:Rcpp:Attributes}.
+
+It may also be a dependency on a fairly standard library available on most if
+not all systems.  The graphics formats bmp, jpeg or png may be an example; text
+formats like JSON or XML are another.  One difficulty, though, may be that
+_run-time_ support does not always guarantee _compile-time_ support. In these
+cases, a `-dev` or `-devel` package may need to be installed.
+
+Here, we use a third approach and copy files. Discussing the two other means
+fully is beyond the scope of this shorter note. So in the concrete case of Corels, we
 
 - copied all existing C++ source and header files over into the `src/` directory;
 - renamed all header files from `*.hh` to `*.h` to comply with an R preference;

diff --git a/vignettes/rmd/Rcpp.bib b/vignettes/rmd/Rcpp.bib
@@ -80,6 +80,14 @@ @Manual{CRAN:anytime
   url =		 CRAN # "package=anytime"
 }
 
+@Manual{CRAN:AsioHeaders,
+  title =        {'Asio' C++ Header Files},
+  author =       {Dirk Eddelbuettel},
+  year =         {2024},
+  note =         {R package version 1.22.1},
+  url =		 CRAN # "package=AsioHeaders"
+}
+
 @Manual{CRAN:BH,
   title =        {BH: Boost C++ Header Files},
   author =       {Dirk Eddelbuettel and John W. Emerson and Michael