[Rcpp-commits] r4031 - in pkg/Rcpp/inst/doc: . Rcpp-attributes

[noreply at r-forge.r-project.org]

Author: jjallaire
Date: 2012-11-24 15:53:14 +0100 (Sat, 24 Nov 2012)
New Revision: 4031

Modified:
   pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
   pkg/Rcpp/inst/doc/Rcpp.bib
Log:
expand discussion of binary compatibility in attributes vignette

Modified: pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw	2012-11-24 08:01:15 UTC (rev 4030)
+++ pkg/Rcpp/inst/doc/Rcpp-attributes/Rcpp-attributes.Rnw	2012-11-24 14:53:14 UTC (rev 4031)
@@ -824,13 +824,28 @@
 
 \subsubsection{Binary Compatibility}
 
-An additional consideration related to exposing \proglang{C++} functions from a package
-is binary compatibility. If a user of your package compiles against 
-one version of your package and then runs against another version the binary
+An additional consideration related to exposing \proglang{C++} types from a 
+package is binary compatibility. If a user of your package compiles against 
+one version of the package and then runs against another version the binary
 layout of \proglang{C++} types used must remain stable in order for things to work
-correctly. The recommended way to minimize binary compatibility problems is to
-only use built-in \proglang{C++} types and \pkg{Rcpp} wrapper types in your interfaces. 
+correctly. Note that this is an issue that affects all \proglang{C++} interfaces
+exposed by shared libraries and is not specific to \proglang{R} packages or 
+\pkg{Rcpp}. A summary of the issues presented can be found in
+`\textsl{Binary Compatibility Issues with C++}' \citep{KDE-TechBase:2012}.
 
+Note that if your package is used within a \proglang{C++} source file compiled with
+\texttt{sourceCpp} then binary compatability is not a concern (because the 
+compilation is always synchronized with the currently installed version of your
+package). Also, packages published on \texttt{CRAN} are automatically rebuilt when a
+package they depend on via \texttt{LinkingTo} is updated, so users with updated
+versions of all packages will similarly not have binary compatibility problems.
+
+However, even when installing from \texttt{CRAN} it's possible for users to
+have the latest version of one package but not of another. If you want to
+minimize binary compatibility problems even in the face of out-of-sync package
+versions then it's strongly recommended that you use only use built-in
+\proglang{C++} types and \pkg{Rcpp} wrapper types in your interfaces. 
+
 \bibliographystyle{plainnat}
 \bibliography{Rcpp}
 

Modified: pkg/Rcpp/inst/doc/Rcpp.bib
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp.bib	2012-11-24 08:01:15 UTC (rev 4030)
+++ pkg/Rcpp/inst/doc/Rcpp.bib	2012-11-24 14:53:14 UTC (rev 4031)
@@ -506,3 +506,11 @@
   publisher =	 {Springer-Verlag},
   address =	 {London},
 }
+
+ at misc{KDE-TechBase:2012,
+  author = {KDE-TechBase},
+  title = {Binary Compatibility Issues With {C++}},
+  howpublished = "\url{http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++}",
+  year = {2012}, 
+  note = "[Online; accessed 24-November-2012]"
+}