add 'compileAttributes() twice' to Rcpp-FAQ (closes #745)

Author: eddelbuettel

ChangeLog

@@ -1,8 +1,11 @@
+2017-09-21  Dirk Eddelbuettel  <[email protected]>
+
+        * vignettes/Rcpp-FAQ.Rmd (Rcpp): Add entry for 'symbols not found' error
+        requiring two runs of compileAttributes
+
 2017-09-20  James J Balamuta  <[email protected]>
 
-        * DESCRIPTION (Version, Date): Roll minor version
-        * vignettes/jss.bst: Removed
-        * vignettes/rcpp-docs.cls: idem
+        * vignettes/rcpp-docs.cls: Removed
 
 2017-09-20  Dirk Eddelbuettel  <[email protected]>
 

inst/NEWS.Rd

@@ -24,9 +24,11 @@
       addressing issue \ghit{682}).
       \item Added a new vignette \sQuote{Rcpp-introduction} based on new PeerJ
       preprint, renamed existing introduction to \sQuote{Rcpp-jss-2011}.
-      \item Transitioned all vignettes to the pinp RMarkdown template
+      \item Transitioned all vignettes to the 'pinp' RMarkdown template
       (James Balamuta and Dirk Eddelbuettel in \ghpr{755} addressing
       issue \ghit{604}).
+      \item Added an entry on running `compileAttributes()` twice to the
+      Rcpp-FAQ (\ghit{#745}).
     }
   }
 }

vignettes/Rcpp-FAQ.Rmd

@@ -1684,4 +1684,29 @@ sort(x)
 rcpp_sort(x)
 ```
 
+## Package building fails with 'symbols not found' 
+
+R 3.4.0 and later strongly encourage registering dynamically loadable
+symbols. In the stronger form (where `.registration=TRUE` is added to the
+`useDynLib()` statement in `NAMESPACE`), only registered symbols can be
+loaded. This is fully supported by Rcpp 0.12.12 and later, and the required code
+is added to `src/RcppExports.cpp`.
+
+However, the transition from the previously generated file `src/RcppExports.cpp`
+to the new one may require running `compileAttributes()` twice (which does not
+happen when, _e.g., devrtools is used). When `Rcpp::compileAttributes()` is
+called, it also calls `tools::package_native_routine_registration_skeleton()`,
+which crawls through usages of `.Call()` in the `R/` source files of the package to
+figure out what routines need to be registered. If an older `RcppExports.R` file
+is discovered, its out-of-date symbol names get picked up, and registration
+rules for those symbols get written as well. This will register more symbols for
+the package than are actually defined, leading to an error. This point has been
+discussed at some length both in the GitHub issue tickes, on StackOverflow and
+elsewhere.
+
+So if your autogenerated file fails, and a `symbols not found` error is reported
+by the linker, consider running `compileAttributes()` twice. Deleting
+`R/RcppExports.R` and `src/RcppExports.cpp` may also work. 
+
+
 \newpage