README.md 15.6 KB
Newer Older
Kyle Edwards's avatar
Kyle Edwards committed
1 2 3 4 5 6 7
Introduction
============

`dh-cmake` is a set of Debhelper utilities for packaging CMake projects on
Debian systems. It consists of three main Debhelper sequences: `cmake`,
`ctest`, and `cpack`.

8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
### What About `--buildsystem=cmake`?

If you've ever packaged a CMake project for Debian before, you probably know
that Debhelper includes a `--buildsystem=cmake` option to handle the configure,
build, and test steps. `dh-cmake` does not replace this option, but instead
complements it with additional CMake functionality, such as:

* Basic CMake component installation (for example, separate packages for
  `Development` and `Runtime` components)
* Integration with CTest dashboard mode to submit build and test logs to CDash
  (for continuous integration on Debian systems)
* Advanced CPack component and component group installation and dependency
  metadata (for example, if CPack component A depends on component B, this will
  be reflected in the generated Debian packages)

The Debhelper team has done an excellent job of incorporating the CMake
buildsystem into Debian, and our hope is that `dh-cmake` will make it even
easier to package CMake projects on Debian. If you package a CMake project on
Debian, you should use both the Debhelper CMake buildsystem AND `dh-cmake`.

Note: as of Debhelper 11.2, you can use CMake's Ninja generator, by declaring
`--buildsystem=cmake+ninja`. Kitware highly recommends using this option,
especially for large projects, because it will speed up build time
significantly.

Kyle Edwards's avatar
Kyle Edwards committed
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
cmake
-----

The `cmake` Debhelper sequence provides the `dh_cmake_install` command, which
uses CMake's install components feature to put files into their proper
packages.

Let's say you have the following `CMakeLists.txt` file:

```cmake
cmake_minimum_required(VERSION 3.12)
project(example C)

include(GNUInstallDirs)

48
add_library(example SHARED example.c)
Kyle Edwards's avatar
Kyle Edwards committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
set_target_properties(example PROPERTIES
  PUBLIC_HEADER "example.h"
  VERSION 1.0
  SOVERSION 1
)
install(TARGETS example
  LIBRARY
    DESTINATION "${CMAKE_INSTALL_LIBDIR}"
  PUBLIC_HEADER
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
)
```

And then your `debian/rules` file will look like this:

```makefile
65 66
#!/usr/bin/make -f

Kyle Edwards's avatar
Kyle Edwards committed
67 68 69 70
%:
        dh $@ --buildsystem=cmake
```

71 72 73 74 75 76
And a `debian/control` file (minimalistic, many fields have been omitted for
brevity):

```
Source: libexample
Maintainer: Example <example@example.com>
77
Build-Depends: cmake (>= 3.12), debhelper (>= 11)
78 79 80 81 82 83 84 85 86 87

Package: libexample
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}

Package: libexample-dev
Architecture: any
Depends: libexample (= ${binary:Version}), ${misc:Depends}
```

Kyle Edwards's avatar
Kyle Edwards committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
You might then have a `debian/libexample.install` file with the following:

```
usr/lib/*/*.so.*
```

and a `debian/libexample-dev.install` file with the following:

```
usr/lib/*/*.so
usr/include
```

This works, but if you have a large project that installs lots of files in
different directories, making a `*.install` file that lists all of them can be
difficult to maintain.

CMake provides a way to break an installation up into components, and
`dh_cmake_install` takes advantage of this functionality. Let's revise our
`CMakeLists.txt` file:

Kyle Edwards's avatar
Kyle Edwards committed
109
```cmake
Kyle Edwards's avatar
Kyle Edwards committed
110 111 112 113 114
cmake_minimum_required(VERSION 3.12)
project(example C)

include(GNUInstallDirs)

115
add_library(example SHARED example.c)
Kyle Edwards's avatar
Kyle Edwards committed
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
set_target_properties(example PROPERTIES
  PUBLIC_HEADER "example.h"
  VERSION 1.0
  SOVERSION 1
)
install(TARGETS example
  LIBRARY
    DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    COMPONENT Libraries
    NAMELINK_COMPONENT Development
  PUBLIC_HEADER
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
    COMPONENT Development
)
```

Revised `debian/rules` file:

Kyle Edwards's avatar
Kyle Edwards committed
134
```makefile
135 136
#!/usr/bin/make -f

Kyle Edwards's avatar
Kyle Edwards committed
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
%:
        dh $@ --buildsystem=cmake --with cmake
```

The `--with cmake` argument causes the `cmake` Debhelper sequence to be loaded,
which takes advantage of the `COMPONENT` arguments in the `install()` commands.
Now let's get rid of `debian/libexample.install` and replace it with a file
called `debian/libexample.cmake-components`:

```
Libraries
```

And delete `debian/libexample-dev.install` and replace it with a file called
`debian/libexample-dev.cmake-components`:

```
Development
```

157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
Add `dh-cmake` to your project's `Build-Depends`:

```
Source: libexample
Maintainer: Example <example@example.com>
Build-Depends: cmake (>= 3.12), dh-cmake, debhelper (>= 11)

Package: libexample
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}

Package: libexample-dev
Architecture: any
Depends: libexample (= ${binary:Version}), ${misc:Depends}
```

Finally, make a file called `debian/dh-cmake.compat`:

```
1
```

This tells `dh-cmake` to use its own compat level 1 when it runs. This file is
similar in concept to Debhelper's own `debian/compat` file, but it lives in its
own file to avoid being tied to Debhelper versions. As `dh-cmake` is further
developed, backwards-incompatible changes will only occur in newer compat
levels. Currently, the only available compat level is 1.

Kyle Edwards's avatar
Kyle Edwards committed
185 186 187 188 189
Now, there's no more need to keep track of filename patterns, because the CMake
component system puts the correct files in the correct packages.

ctest
-----
190 191 192 193 194 195 196 197 198 199 200 201

The `ctest` sequence integrates CTest and CDash into the Debian build process.
Projects that are CTest-aware can use `--with ctest` to run CTest in dashboard
mode during a build and submit configure, build, and test logs to the CDash
server listed in the project's `CTestConfig.cmake` file. The `ctest` sequence
is designed to bring Kitware's software process to the Debian build system.

Note: `--with ctest` is primarily for use in packages that are under
development and trying to achieve Debian policy compliance. It is designed to
monitor the health of the project when being built in a Debian environment. It
is not primarily intended for use in production packages.

202
`--with ctest` adds four new commands to the Debhelper `build` sequence:
203 204 205 206 207 208 209

* `dh_ctest_start`
* `dh_ctest_configure`
* `dh_ctest_build`
* `dh_ctest_test`

By default, the `configure`, `build`, and `test` steps are simple wrappers
210 211 212 213
around their `dh_auto_*` counterparts, and the `start` step does nothing.
However, they recognize a new environment variable, `DEB_CTEST_OPTIONS`, which
can be used to activate CTest's dashboard mode. To activate dashboard mode, do
the following:
214 215 216 217 218 219

```bash
DEB_CTEST_OPTIONS="model=Experimental submit" dpkg-buildpackage
```

The `model` argument will set the CTest dashboard model to "Experimental". You
220 221
can also set it to "Continuous" or "Nightly". The `submit` argument tells each
`dh_ctest_*` command to submit its own results to CDash (it does not submit by
222 223 224
default, due to the fact that the package may be building in an environment
without internet access.)

225 226 227 228 229 230
When used without any options, the `configure`, `build`, and `test` steps each
submit their own results to CDash upon completion, but you can disable this
behavior by passing a `--no-submit` option to them. You can also submit results
explicitly with another optional command, `dh_ctest_submit`, which is not
included in `--with ctest` by default.

231 232 233 234 235 236
Note: if you pass `--no-submit`, you must pass it in the form `-O--no-submit`,
because the `dh_ctest_*` commands pass ALL of their arguments to their
`dh_auto_*` counterparts, which don't recognize the `--no-submit` parameter.
Putting it in a `-O` parameter keeps them from throwing an error due to an
unrecognized parameter.

237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
Note that the steps above correspond closely to CTest's
[Dashboard Client Steps](https://cmake.org/cmake/help/latest/manual/ctest.1.html#dashboard-client-steps).
Under the hood, they call the corresponding `ctest_*()` commands.

Let's add some tests to our `CMakeLists.txt` file:

```cmake
cmake_minimum_required(VERSION 3.12)
project(example C)

include(GNUInstallDirs)
include(CTest)

add_library(example SHARED example.c)
set_target_properties(example PROPERTIES
  PUBLIC_HEADER "example.h"
  VERSION 1.0
  SOVERSION 1
)
install(TARGETS example
  LIBRARY
    DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    COMPONENT Libraries
    NAMELINK_COMPONENT Development
  PUBLIC_HEADER
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
    COMPONENT Development
)

add_test(TestSuccess true)

option(EXAMPLE_RUN_BAD_TEST OFF)
if(EXAMPLE_RUN_BAD_TEST)
  add_test(TestFailure false)
endif()
```

And add a `CTestConfig.cmake` file:

```cmake
set(CTEST_PROJECT_NAME "example")
set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")

set(CTEST_DROP_METHOD "http")
set(CTEST_DROP_SITE "cdash.example.com")
set(CTEST_DROP_LOCATION "/submit.php?project=example")
set(CTEST_DROP_SITE_CDASH TRUE)
```

And finally update our `debian/rules` file:

```makefile
289 290
#!/usr/bin/make -f

291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308
%:
        dh $@ --buildsystem=cmake --with cmake --with ctest
```

Now the project is CTest-aware, and you can build the Debian package and run
the test suite at the same time.

Note: if you are running the build in an isolated environment, and you want to
submit the test results to CDash, you will need to make sure that internet
access is enabled in the build environment.

Because the CTest commands are wrappers around their `dh_auto_*` counterparts,
you can pass arguments to them the way you would to the `dh_auto_*` commands.
Notice above that we added a test, `TestFailure`, that is disabled by default
because of the `EXAMPLE_RUN_BAD_TEST` option. To activate it, change your
`debian/rules` file to look like the following:

```makefile
309 310
#!/usr/bin/make -f

311 312 313 314
%:
        dh $@ --buildsystem=cmake --with cmake --with ctest

override_dh_ctest_configure:
315
        dh_ctest_configure -- -DEXAMPLE_RUN_BAD_TEST:BOOL=ON
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330
```

Now `dh_ctest_configure` will enable the bad test.

Note: in the default mode, because `dh_ctest_test` simply calls `dh_auto_test`,
it will still fail if any of the tests fail. However, in dashboard mode, CTest
allows tests to fail without failing the entire build process, and
`dh_ctest_test` reflects this behavior, so that the package can still build in
development even if some of the tests fail.

### A Word About Privacy

CTest and CDash are designed to aggregate test results from many machines onto
a single dashboard, to enable developers to easily monitor the health of a
software project on a variety of different platforms. However, privacy is also
331 332
very important, and as mentioned above, `dh_ctest_*` commands will not attempt
to submit results to a CDash server unless `DEB_CTEST_OPTIONS` has both `model`
333
AND `submit` activated. The `ctest` sequence will NEVER perform internet access
334 335
without your consent. The `dh-cmake` test suite has tests to make sure the
submit functionality behaves properly. If `dh-cmake` ever performs a rogue
336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356
submission, it is an extremely serious bug, and should be reported immediately.
You are encouraged to monitor your network traffic to ensure the security of
your network.

Additionally, `DEB_CTEST_OPTIONS` should NOT be set from inside the package
scripts, but instead be set externally by the developer or machine building the
package. Packages that enable `submit` in `DEB_CTEST_OPTIONS` from inside
`debian/rules` or another script inside the package should be regarded as
malware.

If you want to run dashboard mode without submitting results from inside the
build process, simply omit the `submit` parameter from `DEB_CTEST_OPTIONS`:

```bash
DEB_CTEST_OPTIONS="model=Experimental" dpkg-buildpackage
```

This can also be useful for submitting results without enabling internet
access inside your isolated build environment: the `dh_ctest_*` commands store
their logs in `debian/.ctest`, so you can write a CTest dashboard script that
submits these logs after the package build process has completed.
Kyle Edwards's avatar
Kyle Edwards committed
357 358 359

cpack
-----
360 361 362 363 364 365 366

The `cpack` Debhelper sequence provides integration with CPack's component
system. If a CMake project is CPack aware, you can have binary packages
correspond to CPack components or component groups, with the CPack dependency
graph propagated into the output packages. The `cpack` sequence takes advantage
of the new "CPack External" generator available in CMake 3.13.

Kyle Edwards's avatar
Kyle Edwards committed
367
`--with cpack` adds three new commands to the Debhelper `install` sequence:
368 369 370 371 372 373

* `dh_cpack_generate`
* `dh_cpack_substvars`
* `dh_cpack_install`

`dh_cpack_generate` does the initial generation with CPack, which generates a
Kyle Edwards's avatar
Kyle Edwards committed
374
JSON file containing CPack metadata for `dh-cmake` to use. `dh_cpack_substvars`
375 376 377 378 379 380 381 382 383 384 385 386 387
reads this JSON file and writes the CPack dependencies to a new substvars
variable, `${cpack:Depends}`. Finally, `dh_cpack_install` is very similar to
`dh_cmake_install` in that it installs components into a package, but it can
also install entire CPack component groups into a package instead of having to
enumerate every component in the component group. `dh_cpack_install` also has
the limitation that the component or component group must be listed in the
CMake project with `cpack_add_component()` or `cpack_add_component_group()`
respectively.

To use the `cpack` sequence, update your `debian/rules` file to look like the
following:

```makefile
388 389
#!/usr/bin/make -f

390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405
%:
        dh $@ --buildsystem=cmake --with cpack --with ctest
```

Note that we have removed the `cmake` sequence here, because in our use case,
the `cpack` sequence provides a more advanced version of the same features.
However, there's no reason why you can't use `cmake` and `cpack` together if
you want to.

Now update your `CMakeLists.txt` file to look like this:

```cmake
cmake_minimum_required(VERSION 3.12)
project(example C)

include(GNUInstallDirs)
406
include(CTest)
407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424
include(CPackComponent)

add_library(example SHARED example.c)
set_target_properties(example PROPERTIES
  PUBLIC_HEADER "example.h"
  VERSION 1.0
  SOVERSION 1
)
install(TARGETS example
  LIBRARY
    DESTINATION "${CMAKE_INSTALL_LIBDIR}"
    COMPONENT Libraries
    NAMELINK_COMPONENT Namelinks
  PUBLIC_HEADER
    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
    COMPONENT Headers
)

425 426 427 428 429 430 431
add_test(TestSuccess true)

option(EXAMPLE_RUN_BAD_TEST OFF)
if(EXAMPLE_RUN_BAD_TEST)
  add_test(TestFailure false)
endif()

432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479
cpack_add_component(Libraries)
cpack_add_component(Namelinks GROUP Development DEPENDS Libraries)
cpack_add_component(Headers GROUP Development DEPENDS Libraries)

cpack_add_component_group(Development)

include(CPack)
```

Note that we have changed the `COMPONENT` of the `PUBLIC_HEADER` block and the
`NAMELINK_COMPONENT` of the `LIBRARY` block to be separate components, and we
have placed both of these components in the `Development` component group. This
is to demonstrate the group functionality of the `cpack` sequence. We have also
added `DEPENDS` fields to the `Namelinks` and `Headers` components so they
depend on `Libraries`.

Since we have switched to `cpack`, rename `debian/libexample.cmake-components`
to `debian/libexample.cpack-components`. This is the file that will be read by
`dh_cpack_substvars` and `dh_cpack_install`. In addition, rename
`debian/libexample-dev.cmake-components` to
`debian/libexample-dev.cpack-component-groups`. We are doing a simple rename
here because the old component name was `Development`, and the new group name
is also `Development`.

Finally, update `debian/control` to look like the following:

```
Source: libexample
Maintainer: Example <example@example.com>
Build-Depends: cmake (>= 3.13), dh-cmake, debhelper (>= 11)

Package: libexample
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}

Package: libexample-dev
Architecture: any
Depends: ${cpack:Depends}, ${misc:Depends}
```

Note that we have bumped the CMake version to 3.13 for the CPack External
generator, and we have also replaced the `libexample` dependency in
`libexample-dev` with `${cpack:Depends}`. This is a new field added by
`dh_cpack_substvars`, which uses the `DEPENDS` field from
`cpack_add_component()` to automatically generate this dependency. This may not
be a big deal for small projects, but for a large project with lots of output
packages, automatically using the dependency graph from CPack can be very
useful.