Difference between revisions of "Example libbu"

(detailed intro to compiling against BRL-CAD APIs)
 
 
Line 15: Line 15:
 
</code>
 
</code>
  
To compile, you need to specify paths to headers (so the #include lines work).
+
Building software involves compiling source code, linking objects, and running our application. No matter what compiler or operating system you use, there are options for all three of those:
* For gcc/clang, this is usually -I options.
+
To link, you need to specify paths and libraries to link (so it can find functions).
+
* For gcc/clang, this is usually -L options and -l options.
+
To run, you need to specify run paths to libraries (so it can use functions).
+
* For gcc/clang, this is usually an -rpath linker option.
+
  
So say we put that <code>test.cpp</code> file in ~/brlcad and have BRL-CAD compiled at ~/brlcad/.build but not installed.  (You don't need to install to use any library -- you just need to know where to find its headers and libraries!)  After changing directory to ~/brlcad, we can compile and link our little test program:
+
* To ''compile'', you need to specify paths to headers (so the #include lines work).
 +
** For gcc/clang, this is usually -I options.
 +
* To ''link'', you need to specify paths and libraries to link (so it can find functions).
 +
** For gcc/clang, this is usually -L options and -l options.
 +
* To ''run'', you need to specify run paths to libraries (so it can use functions).
 +
** For gcc/clang, this is usually an -rpath linker option.
 +
 
 +
So say we put that <code>test.cpp</code> file in ~/brlcad and have BRL-CAD compiled at ~/brlcad/.build but not installed.  (You don't need to install to use any library -- you just need to know where to find headers and libs!)  After changing directory to ~/brlcad, we can compile, link, and run our little test program:
  
 
<code><pre>
 
<code><pre>
 
c++ -c -Iinclude -I.build/include test.cpp
 
c++ -c -Iinclude -I.build/include test.cpp
 
c++ test.o -L.build/lib -Wl,-rpath -Wl,.build/lib -lbu
 
c++ test.o -L.build/lib -Wl,-rpath -Wl,.build/lib -lbu
 +
./a.out
 
</pre></code>
 
</pre></code>
  
Woot!  Let's run to see it in action:
+
Woot!  If you didn't confuse l with 1, put the wrong path, or mix something else up, you should see:
  
<code><pre>
+
<code>
./a.out
+
Program name is a.out
Program name is a.out
+
</code>
</pre></code>
+
  
So that's all there is to it!  We can even simplify the entire process into one compile+link command if we are careful enough to make sure include flags come ''before'' source files and linker flags come ''after'' the source files, like this:
+
And that's essentially all there is to it!  We can even simplify the entire process into one compile+link command if we are careful enough to make sure include flags come ''before'' source files and linker flags come ''after'' the source files in the right order:
  
 
<code>
 
<code>
Line 42: Line 44:
 
</code>
 
</code>
  
From there, we can use any function in LIBBU.  If we want to link against another library like LIBRT or LIBGED, we already have the right paths specified so we'd simply add -lrt or -lged respectively to the link line.  To find functions, we can browse around the include/ headers and subdirectories as nearly every public function is documented in detail there, often with code snippet examples.
+
From there, we set up to use any function in LIBBU.  If we want to link against another library like LIBRT or LIBGED, we already have the right paths so we'd simply add -lrt or -lged respectively to the link line.  To find functions, we can browse around the headers and subdirs in the include directory as nearly every public function is documented in detail there with comments, often with code snippet examples too.
  
Even if we installed BRL-CAD into /opt/brlcad and want to use all headers and all the core libraries, the process remains the same.  Specify paths to headers, source file(s), paths to libs, and then libs:
+
If we already installed BRL-CAD into /opt/brlcad and want to use all headers and all the core libraries, the process remains the same.  Specify paths to headers, source file(s), paths to libs, and then the libs need:
  
 
<code>
 
<code>

Latest revision as of 00:56, 12 December 2017

Compiling against any of BRL-CAD's 20+ libraries is generally quite straight forward. Say you have a simple C++ source file named test.cpp using LIBBU, BRL-CAD's basic utility library:

#include "bu.h"
#include <iostream>

int
main(int ac, char *av[]) {
    bu_setprogname(av[0]);
    std::cout << "Program name is " << bu_getprogname() << std::endl;
    return 0;
}

Building software involves compiling source code, linking objects, and running our application. No matter what compiler or operating system you use, there are options for all three of those:

  • To compile, you need to specify paths to headers (so the #include lines work).
    • For gcc/clang, this is usually -I options.
  • To link, you need to specify paths and libraries to link (so it can find functions).
    • For gcc/clang, this is usually -L options and -l options.
  • To run, you need to specify run paths to libraries (so it can use functions).
    • For gcc/clang, this is usually an -rpath linker option.

So say we put that test.cpp file in ~/brlcad and have BRL-CAD compiled at ~/brlcad/.build but not installed. (You don't need to install to use any library -- you just need to know where to find headers and libs!) After changing directory to ~/brlcad, we can compile, link, and run our little test program:

c++ -c -Iinclude -I.build/include test.cpp
c++ test.o -L.build/lib -Wl,-rpath -Wl,.build/lib -lbu
./a.out

Woot! If you didn't confuse l with 1, put the wrong path, or mix something else up, you should see:

Program name is a.out

And that's essentially all there is to it! We can even simplify the entire process into one compile+link command if we are careful enough to make sure include flags come before source files and linker flags come after the source files in the right order:

c++ -Iinclude -I.build/include test.cpp -L.build/lib -Wl,-rpath -Wl,.build/lib -lbu

From there, we set up to use any function in LIBBU. If we want to link against another library like LIBRT or LIBGED, we already have the right paths so we'd simply add -lrt or -lged respectively to the link line. To find functions, we can browse around the headers and subdirs in the include directory as nearly every public function is documented in detail there with comments, often with code snippet examples too.

If we already installed BRL-CAD into /opt/brlcad and want to use all headers and all the core libraries, the process remains the same. Specify paths to headers, source file(s), paths to libs, and then the libs need:

c++ -I/opt/brlcad/include -I/opt/brlcad/include/brlcad -I/opt/brlcad/include/openNURBS test.cpp -L/opt/brlcad/lib -Wl,-rpath -Wl,/opt/brlcad/lib -lged -lrt -lbn -lbu

Happy coding!