From bbdc9f5709c28a89c706da9020d680fc720a85f2 Mon Sep 17 00:00:00 2001
From: Dirk Eddelbuettel <edd@debian.org>
Date: Sat, 25 Jan 2025 07:47:47 -0600
Subject: [PATCH] Expand libraries vignette with PACKAGE_types.h

---
 vignettes/rmd/Rcpp-libraries.Rmd | 27 ++++++++++++++++++---------
 vignettes/rmd/Rcpp.bib           |  8 ++++++++
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/vignettes/rmd/Rcpp-libraries.Rmd b/vignettes/rmd/Rcpp-libraries.Rmd
index 80d641735..748abef39 100644
--- 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 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
index 0c9e40555..527a12cee 100644
--- 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