title: Using 3rd party header files with Rcpp
body: <p>I have a header file called <code>coolStuff.h</code> that contains a function <code>awesomeSauce(arg1)</code> that I would like to use in my cpp source file.</p>
  
  <p>Directory Structure:</p>
  
  <ul>
  <li>RworkingDirectory
  
  <ul>
  <li>sourceCpp
  
  <ul>
  <li>theCppFile.cpp</li>
  </ul></li>
  <li>cppHeaders
  
  <ul>
  <li>coolStuff.h</li>
  </ul></li>
  </ul></li>
  </ul>
  
  <p>The Code:</p>
  
  <pre><code>#include &lt;Rcpp.h&gt;
  #include &lt;cppHeaders/coolStuff.h&gt;
  using namespace Rcpp;
  
  // [[Rcpp::export]]
  double someFunctionCpp(double someInput){
  
   double someOutput = awesomeSauce(someInput);
  
  return someOutput;
  }
  </code></pre>
  
  <p>I get the error:</p>
  
  <pre><code> theCppFile.cpp:2:31: error: cppHeaders/coolStuff.h: No such file or directory
  </code></pre>
  
  <p>I have moved the file and directory all over the place and can't seem to get this to work. I see examples all over the place of using 3rd party headers that say just do this:</p>
  
  <pre><code>#include &lt;boost/array.hpp&gt;
  </code></pre>
  
  <p>(Thats from Hadley/devtools)</p>
  
  <p><a href="https://github.com/hadley/devtools/wiki/Rcpp" rel="noreferrer">https://github.com/hadley/devtools/wiki/Rcpp</a></p>
  
  <p>So what gives? I have been searching all morning and can't find an answer to what seems to me like a simple thing.</p>
  
  <h2>UPDATE 01.11.12</h2>
  
  <p>Ok now that I have figured out how to build packages that use Rcpp in Rstudio let me rephrase the question. I have a stand alone header file coolStuff.h that contains a function I want to use in my cpp code. </p>
  
  <p>1) Where should I place coolStuff.h in the package directory structure so the function it contains can be used by theCppFile.cpp? </p>
  
  <p>2) How do I call coolStuff.h in the cpp files? Thanks again for your help. I learned a lot from the last conversation. </p>
  
  <p>Note: I read the vignette "Writing a package that uses Rcpp" and it does not explain how to do this. </p>
  
  <h2>The Answer:</h2>
  
  <p><em>Ok let me summarize the answer to my question since it is scattered across this page. If I get a detail wrong feel free to edit this or let me know and I will edit it:</em></p>
  
  <p>So you found a <code>.h</code> or <code>.cpp</code> file that contains a function or some other bit of code you want to use in a <code>.cpp</code> file you are writing to use with <code>Rcpp</code>. </p>
  
  <p>Lets keep calling this found code <code>coolStuff.h</code> and call the function you want to use <code>awesomeSauce()</code>. Lets call the file you are writing <code>theCppFile.cpp</code>.</p>
  
  <p>(I should note here that the code in .h files and in .cpp files is all C++ code and the difference between them is for the C++ programer to keep things organized in the proper way. I will leave a discussion of the difference out here, but a simple search here on SO will lead you to discussion of the difference. For you the R programer needing to use a bit o' code you found, there is no real difference.) </p>
  
  <p><strong>IN SHORT:</strong> You can use a file like <code>coolStuff.h</code> provided it calls no other libraries, by either cut-and-pasteing into <code>theCppFile.cpp</code>, or if you create a package you can place the file in the <code>\src</code> directory with the <code>theCppFile.cpp</code> file and use <code>#include "coolStuff.h"</code> at the top of the file you are writing. The latter is more flexible and allows you to use functions in <code>coolStuff.h</code> in other <code>.cpp</code> files.</p>
  
  <p><strong>DETAILS:</strong></p>
  
  <p>1) <code>coolStuff.h</code> must not call other libraries. So that means it cannot have any include statements at  the top. If it does, what I detail below probably will not work, and the use of found code that calls other libraries is beyond the scope of this answer.</p>
  
  <p>2) If you want to compile the file with <code>sourceCpp()</code> you need to cut and paste <code>coolStuff.h</code> into <code>theCppFile.cpp</code>. I am told there are exceptions, but <code>sourceCpp()</code> is designed to compile one <code>.cpp</code> file, so thats the best route to take. </p>
  
  <p>(NOTE: I make no guarantees that a simple cut and paste will work out of the box. You may have to rename variables, or more likely switch the data types being used to be consistent with those you are using in <code>theCppFile.cpp</code>.  But so far, cut-and-paste has worked with minimal fuss for me with 6 different simple <code>.h</code> files)</p>
  
  <p>3) If you only need to use code from <code>coolStuff.h</code> in <code>theCppFile.cpp</code> and nowhere else, then you should cut and paste it into <code>theCppFile.cpp</code>.</p>
  
  <p>(Again I make no guarantees see the note above about cut-and-paste)</p>
  
  <p>4) If you want to use code contained in <code>coolStuff.h</code> in <code>theCppFile.cpp</code> AND other <code>.cpp</code> files, you need to look into building a package. This is not hard, but can be a bit tricky, because the information out there about building packages with Rcpp ranges from the exhaustive thorough documentation you want with any R package (but that is above your head as a newbie), and the newbie sensitive introductions (that may leave out a detail <em>you</em> happen to need).</p>
  
  <p>Here is what I suggest:</p>
  
  <p>A) First get a version of <code>theCppFile.cpp</code> with the code from <code>coolStuff.h</code> cut-and-paste into <code>theCppFile.cpp</code> that compiles with <code>sourceCpp()</code> and works as you expect it to. This is not a must, but if you are new to Rcpp OR packages, it is nice to make sure your code works in this simple situation before you move to the more complicated case below.</p>
  
  <p>B) Now build your package using <code>Rcpp.package.skeleton()</code> or use the Build functionality in RStudio (HIGHLY recommended). You can find details about using <code>Rcpp.package.skeleton()</code> in <a href="https://github.com/hadley/devtools/wiki/Rcpp" rel="noreferrer">hadley/devtools</a> or <a href="http://dirk.eddelbuettel.com/code/rcpp/Rcpp-attributes.pdf" rel="noreferrer">Rcpp Attributes Vignette</a>. The full documentation for writing packages with Rcpp is in the <a href="http://cran.rstudio.com/web/packages/Rcpp/vignettes/Rcpp-package.pdf" rel="noreferrer">Writing a package that uses Rcpp</a>, however this one assumes you know your way around C++ fairly well, and does not use the new "Attributes" way of doing Rcpp. </p>
  
  <p>Don't forget to "Build &amp; Reload" if using RStudio or <code>compileAttributes()</code> if you are not in RStudio. </p>
  
  <p>C) Now you should see in your \R directory a file called <code>RcppExports.R</code>. Open it and check it out. In <code>RcppExports.R</code> you should see the R wrapper functions for all the .cpp files you have in your <code>\src</code> directory. Pretty sweet.</p>
  
  <p>D) Try out the R function that corresponds to the function you wrote in <code>theCppFile.cpp</code>. Does it work? If so move on. </p>
  
  <p>E) With your package built you can move <code>coolStuff.h</code> into the <code>src</code> folder with <code>theCppFile.cpp</code>.</p>
  
  <p>F) Now you can remove the cut-and-paste code from <code>theCppFile.cpp</code> and at the top of <code>theCppFile.cpp</code> (and any other .cpp file you want to use code from coolStuff.h) put <code>#include "coolStuff.h"</code> just after <code>#include &lt;Rcpp.h&gt;</code>. Note that there are no brackets around ranker.h, rather there are "". This is a C++ convention when including local files provided by the user rather than a library file like Rcpp or STL etc...</p>
  
  <p>G) Now you have to rebuild the package. In RStudio this is just "Build &amp; Reload" in the Build menu. If you are not using RStudio you should run <code>compileAttributes()</code></p>
  
  <p>H) Now try the R function again just as you did in step D), hopefully it works.</p>