Repository: bulletphysics/bullet3

Issue:
Allow #include <bullet/LinearMath/...>
Currently the bullet header files are installed to `${CMAKE_INSTALL_PREFIX}/include/bullet`, which is good, but the exported include path points to this exact folder, so that users wishing to include bullet files must use the following:

```
#include <LinearMath/btVector3.h>
```

It would be nice to allow the following:

```
#include <bullet/LinearMath/btVector3.h>
```

This helps indicate where header files are coming from (since LinearMath is a pretty generic name) and helps avoid header file name conflicts (however unlikely they may be).

This could be fixed by adding an additional `-I` flag to the pkg-config CFLAGS (keeping the existing one for backwards compatibility).



Discussion:
The name 'LinearMath' was badly chosen. Originally I wanted the BulletMath (LinearMath), BulletCollision and BulletDynamics to be independent libraries. I've had similar requests and I consider making that change for Bullet 3.x (but not for Bullet 2.x)

The `LinearMath` name has to stay for 2.x, but this `CFLAGS` proposal may improve clarity if people do `#include <bullet/LinearMath/...>`

I have no idea where Bullet installs its headers when using 'make install'. Can you explain a bit further about your proposal and where the files are installed etc? Do I need to change all the internal #include to use bullet/LinearMath/... or can the internal includes stay LinearMath/...?

Just some background, for anyone interested:
I have only supported static linkage and expect developers to copy the bullet/src folder in their own project. Others insisted in having a 'make install' option, even though I think it is a really bad idea, especially for games: you don't want to switch to a different version of Bullet, because the behavior changes (slightly) and it could break the gameplay. Perhaps for non-gaming apps this is no issue?

I'll respond to your comments about the background first. Among the many use cases of bullet, consider the following two (note that I'm not judging or advocating for either one, just listing them as different types of considerations):
- Monolithic applications that uses bullet and have no downstream developers writing code that links against it (such as games, visual effects software)
- Modular libraries that use bullet and have downstream developers writing code against it (such as the [gazebo robotic simulator](http://gazebosim.org), of which I am a core developer)

I think static linking is fine for monolithic applications, but it causes problems for use in software stacks involving more modularity. When you have multiple pieces of software interacting on a system, there can be problems if different pieces are using different versions of the same library (most prominent in my mind are some difficult linking problems).

Regarding the different behavior of each version, we use [pkg-config in cmake](https://bitbucket.org/osrf/gazebo/src/default/cmake/SearchForStuff.cmake#cl-361) with logic to prefer specific versions of bullet. For example, you fixed some bugs in version 2.81, so we have been requiring version 2.82 or greater for gazebo.

Regarding your specific questions, a source install will have a default `CMAKE_PREFIX_PATH` of `/usr/local`, so the `btVector3.h` header would be installed to:

```
/usr/local/include/bullet/LinearMath/btVector3.h
```

When packaged as a binary for debian systems, the prefix is typically `/usr`, so it would go to:

```
/usr/include/bullet/LinearMath/btVector3.h
```

Using [homebrew](http://brew.sh) on Mac OS X, the prefix is usually `/usr/local/Cellar/bullet/version`, so version 2.82 would be installed to:

```
/usr/local/Cellar/bullet/2.82/include/bullet/LinearMath/btVector3.h
```

but homebrew also makes sym-links to `/usr/local` so it would also be available from

```
/usr/local/include/bullet/LinearMath/btVector3.h
```

As a downstream developer, I can use `pkg-config` or cmake `find_package` to get info about where the header files are installed. The pkg-config file bullet.pc is configure from the template [bullet.pc.cmake](https://github.com/bulletphysics/bullet3/blob/master/bullet.pc.cmake) to add a `-I` argument to the `CFLAGS` variable that resolves to something like the following:

```
-I/usr/include/bullet
```

With that include flag, I can use the following:

```
#include <LinearMath/btVector3.h>
```

If we add another `-I` argument:

```
-I/usr/include/bullet -I/usr/include
```

then the following would work as well (which I prefer):

```
#include <bullet/LinearMath/btVector3.h>
```

Sorry that got a little long-winded. Here's the patch I'm thinking of (I can make a pull request):

```
diff --git a/bullet.pc.cmake b/bullet.pc.cmake
index a504b1f..8b989fa 100644
--- a/bullet.pc.cmake
+++ b/bullet.pc.cmake
@@ -3,4 +3,4 @@ Description: Bullet Continuous Collision Detection and Physics Library
 Requires:
 Version: @BULLET_VERSION@
 Libs: -L@CMAKE_INSTALL_PREFIX@/@LIB_DESTINATION@ -lBulletSoftBody -lBulletDynamics -lBulletCollision -lLinearMath
-Cflags: @BULLET_DOUBLE_DEF@ -I@CMAKE_INSTALL_PREFIX@/@INCLUDE_INSTALL_DIR@
+Cflags: @BULLET_DOUBLE_DEF@ -I@CMAKE_INSTALL_PREFIX@/@INCLUDE_INSTALL_DIR@ -I@CMAKE_INSTALL_PREFIX@/include
```

One other reference point, here's an example `#include` from gazebo:

```
#include <gazebo/physics/physics.hh>
```

For gazebo 5.0, this is installed to the following location:

```
/usr/include/gazebo-5.0/gazebo/physics/physics.hh
```

with the following `-I` flag:

```
-I/usr/include/gazebo-5.0
```


Patch:
diff --git a/bullet.pc.cmake b/bullet.pc.cmake
index a504b1fc41..8b989faba3 100644
--- a/bullet.pc.cmake
+++ b/bullet.pc.cmake
@@ -3,4 +3,4 @@ Description: Bullet Continuous Collision Detection and Physics Library
 Requires:
 Version: @BULLET_VERSION@
 Libs: -L@CMAKE_INSTALL_PREFIX@/@LIB_DESTINATION@ -lBulletSoftBody -lBulletDynamics -lBulletCollision -lLinearMath
-Cflags: @BULLET_DOUBLE_DEF@ -I@CMAKE_INSTALL_PREFIX@/@INCLUDE_INSTALL_DIR@
+Cflags: @BULLET_DOUBLE_DEF@ -I@CMAKE_INSTALL_PREFIX@/@INCLUDE_INSTALL_DIR@ -I@CMAKE_INSTALL_PREFIX@/include