= Changing the build flags for a package =

<<TOC(4)>>

== Default build flags ==

By default our farm uses the `dpkg-buildflags` command to get the default flags for building on Debian/Ubuntu. What this boils down to are these flags:

 * `-DCMAKE_BUILD_TYPE=None`
  * According to the Debian docs, this is done to prevent CMake from overriding other flags which are set.
 * `-O2`
  * This is the default optimization flag for Debian/Ubuntu.
 * `-DNDEBUG`
  * We explicitly add this to all packages by default.

To understand why we have arrived here, please see this issue: https://github.com/ros-infrastructure/bloom/issues/327

== Changing the build flags ==

If you want to change a flag only for building, like opting out of `-DNDEBUG` or opting in to `-O3` for instance, then you will need to modify the default debian configurations in your release repository.

Before you do this, release your package at least once using one of the other tutorials.

You can change the flags by editing the `debian/rules.em` file in the debian release branch for your package. Changing flags is done on a per package and per ROS distro basis, so if you have a release repository with 3 packages in it, then you will need to make 3 patches for each ROS distro. First clone your release repository:

{{{
$ git clone https://github.com/<your organization>/<your RELEASE repository>
}}}

Note, this is your release repository not your upstream repository that you commit your code to.

After cloning your release repository, change to the branch for the package and ROS distro you want to change the flags for:

{{{
$ cd <folder you checked it out to>
$ git checkout debian/<rosdistro>/<package_name>
}}}

For example, if your package name is `foo` and your changing this for Indigo, then you would do something like `git checkout debian/indigo/foo`.

In this branch there will be a folder called `debian` and in that folder there will be template files which have not yet been expanded. One of those templates will be called `rules.em`. You will edit this file and commit the change in order to change the flags.

If you wanted to opt out of the `-DNDEBUG` which is on by default you could remove the lines in the template which do this:

 {{{
# Explicitly enable -DNDEBUG, see:
# 	https://github.com/ros-infrastructure/bloom/issues/327
export DEB_CXXFLAGS_MAINT_APPEND=-DNDEBUG
}}}

If you want to add the `-O3` optimization flag, overriding the default `-O2` flag, then add to the `DEB_CXXFLAGS_MAINT_APPEND` environment variable `-O3`, like so:

 {{{
export DEB_CXXFLAGS_MAINT_APPEND=-DNDEBUG -O3
}}}

Once you have made any modifications you want to make, then commit your changes and push:

{{{
$ git commit -am <some message about how you changed the flags>
$ git push
}}}

Once you have pushed this change you will need to make a new deb-inc release of your release repository for the change to propagate to the farm.

So, once you have made changes for each package and ROS distro which you want to modify, run `bloom-release` again:

{{{
$ bloom-release -r <rosdistro> -t <rosdistro> <repository name>
}}}

This will take you from `<package_version>-0` to `<package_version>-1`, e.g. `0.1.0-0` to `0.1.0-1`, and then open a new pull request. Once merged the farm will use your changes.

You can verify that your changes are in there by checking the tag the build farm uses, e.g. something like `debian/ros-indigo-rviz_0.11.4-1_trusty`.

Future releases of your package, e.g. `0.1.0` to `0.1.1`, will get the patches you have made here, but when releasing for a new ROS distribution you will need to take these steps again as patches like this do not automatically propagate to new ROS distributions.