dcb38d2e30d0395ddca0ad9f70deb7889c00dbb1
[olsrd.git] / lib / info.java / cnf / gradle / doc / BUILDING-GRADLE.md
1 # <a name="Introduction"/>Introduction
2
3 This workspace is setup to be built with [Gradle](http://www.gradle.org).
4
5 The build is setup in such a way that Bnd (OSGi) projects and projects with
6 specific gradle files are automatically included in the build; no editing of
7 Gradle build scripts is needed.
8
9 A simple command in the root of the workspace is enough to build it all:
10
11 ```
12 gradle build
13 ```
14
15 **Note**: The official Bnd Gradle plugin is used so that the same build
16 fidelity is achieved.
17
18 However, compared to the official Bnd Gradle plugin, this workspace build
19 setup adds some extra features to the build...
20
21 First off, the build setup is far more flexible and featureful than the build
22 setup that is delivered by Bndtools itself.
23
24 Among other things it has the following extra features:
25
26 * Support for FindBugs
27 * Support for JUnit code coverage reports through Jacoco
28 * An easily customisable setup
29 * Documentation
30 * Automatic location of the configuration (```cnf```) project
31 * ...and much more
32
33 In order to use this workspace setup in a new workspace, add the
34 URL ```https://gitlab.com/fhuberts/bndtoolsWorkspace.git``` (use
35 the ```origin/master``` branch) to the ```Raw Git Clone URLs``` pane
36 in the Eclipse ```Prefrences->Bndtools->Generated Resources``` window.
37
38 Next time you create an OSGi workspace you can choose to use this
39 workspace setup. If you want to update your workspace with a new version
40 of this workspace setup, then simply do the same as when creating a new
41 workspace, in the existing workspace you want to update.
42
43 This workspace is compatible with Bndtools 2.3.0.REL and later.
44
45
46 # <a name="License"/>License
47
48 This document is licensed under the GNU Free Documentation License,
49 Version 1.3, 3 November 2008
50
51
52 # <a name="OpenSource"/>Open Source
53
54 The plugin was originally developed for - and delivered with - Bndtools 2.3.0
55 but has since been replaced with a different implemention in Bndtools.
56
57 The plugin was thereon forked and now lives on through the support
58 of [Pelagic](http://www.pelagic.nl).
59
60 The project is fully Open Source, licensed under the LGPL, and can be found
61 at [GitLab](https://gitlab.com/fhuberts/bndtoolsWorkspace).
62
63 Contributions are welcome!
64
65
66 # <a name="TableOfContents"/>Table Of Contents
67
68 * [Introduction](#Introduction)
69 * [License](#License)
70 * [Open Source](#OpenSource)
71 * [Table Of Contents](#TableOfContents)
72 * [Installing Gradle](#InstallingGradle)
73   * [On The System](#InstallingGradleOnTheSystem)
74   * [In The Workspace](#InstallingGradleInTheWorkspace)
75 * [Configuring The Gradle Daemon](#ConfiguringTheGradleDaemon)
76 * [Projects & Workspaces](#ProjectsAndWorkspaces)
77   * [Root Project](#ProjectsAndWorkspacesRootProject)
78   * [Sub-Projects](#ProjectsAndWorkspacesSubProjects)
79   * [Gradle Workspace](#ProjectsAndWorkspacesGradleWorkspace)
80   * [Bnd Workspace](#ProjectsAndWorkspacesBndWorkspace)
81   * [Configuration Project](#ProjectsAndWorkspacesCnf)
82   * [Bnd Project Layout](#ProjectsAndWorkspacesBndProjectLayout)
83 * [Build Flow](#BuildFlow)
84 * [Build Tasks](#BuildTasks)
85   * [Bnd Projects](#BuildTasksBndProjects)
86     * [jar](#BuildTasksJar)
87     * [testOSGi](#BuildTasksTestOSGi)
88     * [check](#BuildTasksCheck)
89     * [checkNeeded](#BuildTasksCheckNeeded)
90     * [release](#BuildTasksRelease)
91     * [releaseNeeded](#BuildTasksReleaseNeeded)
92     * [runbundles.<name>](#BuildTasksRunBundlesName)
93     * [runbundles](#BuildTasksRunbundles)
94     * [export.<name>](#BuildTasksExportName)
95     * [export](#BuildTasksExport)
96     * [resolve.<name>](#BuildTasksResolveName)
97     * [resolve](#BuildTasksResolve)
98     * [run.<name>](#BuildTasksRunName)
99     * [testrun.<name>](#BuildTasksTestRunName)
100     * [echo](#BuildTasksEcho)
101     * [bndproperties](#BuildTasksBndProperties)
102     * [clean](#BuildTasksClean)
103     * [cleanNeeded](#BuildTasksCleanNeeded)
104   * [All Projects](#BuildTasksAllProjects)
105     * [clean](#BuildTasksAllClean)
106     * [cleanNeeded](#BuildTasksAllCleanNeeded)
107     * [distClean](#BuildTasksDistClean)
108     * [distcleanNeeded](#BuildTasksDistCleanNeeded)
109   * [Java Projects](#BuildTasksJavaProjects)
110     * [Findbugs](#BuildTasksFindbugs)
111       * [findbugsMain](#BuildTasksFindbugsMain)
112       * [findbugsTest](#BuildTasksFindbugsTest)
113       * [findbugs](#BuildTasksfindbugs)
114       * [findbugstest](#BuildTasksfindbugstest)
115       * [Settings](#FindbugsSettings)
116     * [Jacoco](#BuildTasksJacoco)
117       * [Settings](#BuildTasksJacocoSettings)
118     * [javadoc](#BuildTasksJavadoc)
119       * [Settings](#BuildTasksJavadocSettings)
120     * [clean](#BuildTasksJavaClean)
121   * [Root Project](#BuildTasksRootProject)
122     * [wrapper](#BuildTasksWrapper)
123       * [Settings](#BuildTasksRootProjectSettings)
124 * [Build Options](#BuildOptions)
125   * [Bnd Projects](#BuildOptionsBndProjects)
126   * [Findbugs](#BuildOptionsFindbugs)
127 * [Customising The Build](#CustomisingTheBuild)
128   * [Gradle](#CustomisingTheBuildGradle)
129   * [Bnd](#CustomisingTheBuildBnd)
130 * [Adding Java Projects To The Build](#AddingJavaProjectsToTheBuild)
131 * [OSGi Repository Indexing](#BuildIndexing)
132 * [Jenkins Build Setup](#JenkinsBuildSetup)
133
134
135 # <a name="InstallingGradle"/>Installing Gradle
136
137
138 ## <a name="InstallingGradleOnTheSystem"/>On The System
139
140 Obviously, Gradle must be installed on the system before the workspace can be
141 built with Gradle.
142
143 This description assumes a Linux machine. Details may vary on other OSes.
144
145 * Download Gradle from [http://www.gradle.org](http://www.gradle.org).
146
147 * Unpack the downloaded archive and put it in ```/usr/local/lib```
148   as ```/usr/local/lib/gradle-4.0``` (in case Gradle 4.0 was downloaded).
149
150 * Create a symbolic link to the Gradle installation directory to be able to
151   easily switch Gradle versions later on:
152
153   ```
154   cd /usr/local/lib
155   ln -s gradle-4.0 /usr/local/lib/gradle
156   ```
157
158 * Put the Gradle executable ```/usr/local/lib/gradle/bin/gradle``` on
159   the search path by linking to it from ```/usr/local/bin```:
160
161   ```
162   ln -s /usr/local/lib/gradle/bin/gradle /usr/local/bin/
163   ```
164
165
166 ## <a name="InstallingGradleInTheWorkspace"/>In The Workspace
167
168 Gradle can be installed in the workspace so that the workspace can be built
169 on systems that do not have Gradle installed (like build servers).
170
171 The procedure is:
172
173 * Open a shell and go into the workspace root directory.
174
175 * Assuming Gradle is properly installed on the system
176   (see [Installing Gradle On The System](#InstallingGradleOnTheSystem)), run:
177
178   ```
179   gradle wrapper
180   ```
181
182   If you want to install a specific version of Gradle, then use the
183   following syntax (the example installs Gradle 4.0):
184
185   ```
186   gradle wrapper --gradle-version 4.0
187   ```
188
189 * Commit the files that were created in the workspace to your version control
190   system.
191
192
193 # <a name="ConfiguringTheGradleDaemon"/>Configuring The Gradle Daemon
194
195 Startup times of a Gradle build can be much improved by using the Gradle
196 daemon.
197
198 The Gradle daemon works well when the Gradle build script dependencies are
199 not changed, which makes it well suited to regular development (where these
200 are not changed) but **not** for build servers.
201
202 The daemon can be easily setup by adding the following line
203 to ```~/.gradle/gradle.properties```:
204
205 ```
206 org.gradle.daemon=true
207 ```
208
209 Stopping the Gradle daemon is easily achieved by running:
210
211 ```
212 gradle --stop
213 ```
214
215
216 # <a name="ProjectsAndWorkspaces"/>Projects & Workspaces
217
218
219 ## <a name="ProjectsAndWorkspacesRootProject"/>Root Project
220
221 The Gradle root project is the directory that contains
222 the ```settings.gradle``` file.
223
224 Gradle locates the root project by first looking for
225 the ```settings.gradle``` file in the directory from which it was run,
226 and - when not found - then by searching up in the directory tree.
227
228
229 ## <a name="ProjectsAndWorkspacesSubProjects"/>Sub-Projects
230
231 The build will include all projects in the build that are:
232
233 * **Bnd** projects: Directories directly below the root project with
234                     a ```bnd.bnd``` file.
235
236 * **Gradle** projects: Directories directly below the root project with
237                        a ```build.gradle``` file, **or**
238                        a ```build-settings.gradle``` file.
239
240
241 ## <a name="ProjectsAndWorkspacesGradleWorkspace"/>Gradle Workspace
242
243 The Gradle workspace is rooted in the root project and consists of all
244 included projects - **Bnd** *and* **Gradle** projects.
245
246
247 ## <a name="ProjectsAndWorkspacesBndWorkspace"/>Bnd Workspace
248
249 The Bnd workspace is rooted in the root project and contains exactly one
250 configuration project, and zero or more **Bnd** projects.
251
252 For it to be a *useful* Bnd workspace, it will have to contain at least one
253 Bnd project.
254
255
256 ## <a name="ProjectsAndWorkspacesCnf"/>Configuration Project
257
258 The configuration project is the directory that contains the ```build.bnd```
259 file, and is - by default - the ```cnf``` directory.
260
261 It contains:
262
263 * Placeholder source directory (```src```).
264
265 * Bnd workspace configuration.
266
267   * &nbsp;```ext/*.bnd```
268
269     The ```ext``` directory contains Bnd settings files that are loaded
270     **before** the ```build.bnd``` file.
271
272     The directory typically contains:
273
274     * &nbsp;```junit.bnd```
275
276       This file defines a Bnd variable for the libraries that are needed on
277       the classpath when running JUnit tests.
278
279     * &nbsp;```pluginpaths.bnd```
280
281       This file instructs Bnd to load a number of plugin libraries when it
282       runs. Typically it will not do anything, but its usual purpose is to
283       instruct Bnd to load repository plugins, or custom plugins, by adding
284       them to the ```-pluginpath``` instruction in this file.
285
286     * &nbsp;```repositories.bnd```
287
288       This file configures the plugins that Bnd loads. Typically it will
289       configure the repository plugins that are loaded. However, if any
290       built-in plugins or custom plugins are loaded then these also will
291       have to be configured here. This file also defines which repository
292       is the release repository.
293
294   * &nbsp;```build.bnd```
295
296     This file contains workspace-wide settings for Bnd and will override
297     settings that are defined in any of the ```ext/*.bnd``` files.
298
299 * Repositories.
300
301   * &nbsp;```buildrepo```
302
303     This repository contains libraries that are intended
304     **only for build-time** usage. None are intended to be deployed as
305     bundles into a running OSGi framework, and indeed they may cause
306     unexpected errors if they are used in such a fashion.
307
308   * &nbsp;```localrepo```
309
310     This repository contains no libraries by default. It is intended for
311     external libraries that are needed by one or more of the projects.
312
313   * &nbsp;```releaserepo```
314
315     This repository contains no libraries by default. By default, bundles
316     end up in this repository when they are released from within Eclipse.
317
318   * &nbsp;```releaserepoCI```
319
320     This repository contains no libraries by default. By default, bundles
321     end up in this repository when they are released from a Gradle build
322     (When the Gradle ```-PCI``` option is used).
323
324 * Cache.
325
326   The ```cache``` directory contains libraries that are downloaded by the
327   build. If the build is self-contained then this cache only contains
328   libraries that are retrieved from the workspace itself during the build.
329
330 * Build files.
331
332   * &nbsp;```cnf/gradle```
333
334     This directory contains all Gradle build script files that are used by
335     the Gradle build, dependencies for the build, and documentation
336     pertaining to the build.
337
338     * &nbsp;```template```
339
340       This directory contains build script files that define the build.
341       These are **not** meant to be changed.
342
343     * &nbsp;```custom```
344
345       This directory contains build script files that are hooks into the
346       build process. They allow specification of overrides for various
347       settings, additions to the build, modifications to the build, etc.
348
349       These **are** meant to be changed when build customisations are needed.
350
351     * &nbsp;```dependencies```
352
353       This directory contains libraries that are used by the build in the
354       form of a file repository.
355
356     * &nbsp;```doc```
357
358       This directory contains documentation pertaining to the build. The
359       document you're now reading is located in this directory.
360
361       <a name="svg"/>Also found in this directory is the
362       diagram [template.svg](template.svg) that provides an overview of the
363       build setup, much like the Gradle User Guide shows for the Java Plugin.
364
365       The diagram shows all tasks of the build and their dependencies:
366
367       * The light cyan blocks are tasks that are present by default, either
368         because Gradle creates them by default of because the project has
369         applied the Java plugin, which creates these tasks.
370
371       * The cyan block are tasks that are added or modified by the Bnd plugin.
372       
373       * The orange blocks are tasks that are added or modified by this build
374         setup.
375
376       * The arrows depict **execution flow** (so the dependencies are in the
377         reverse direction).
378
379       * The **red** arrows depict flows from dependent projects (dependencies
380         on projects) .
381
382         For example:
383
384         The ```compileJava``` task of a project is dependent on
385         the ```assemble``` task of another project if the latter project is
386         on the build path of the former project.
387
388       * The **yellow** arrows depict flows to parent projects (dependencies
389         from projects) . These are the reverse of the **red** arrows.
390
391       * The **blue** arrows depict flows/dependencies that are only present
392         when the task from which the flows originate is present in the
393         project.
394
395       * The **green** arrows depict flows/dependencies that are disabled by
396         default.
397
398       * The **magenta** arrows depict flows/dependencies that are
399         automatically scheduled to run when the tasks from which they
400         originate are scheduled to run.
401         
402       * See the
403         [Bnd Gradle plugin README](https://github.com/bndtools/bnd/blob/master/biz.aQute.bnd.gradle/README.md)
404         for details about the Bnd supplied build tasks.
405
406
407 ## <a name="ProjectsAndWorkspacesBndProjectLayout"/>Bnd Project Layout
408
409 A Bnd project has a well defined layout with a number of source directories
410 and one output directory:
411
412 * Main sources: located in the ```src``` directory by default. Compiled
413   sources will be placed in the ```bin``` directory. Can be overridden with
414   the ```src``` and ```bin``` Bnd settings respectively.
415
416 * Test sources: located in the ```test``` directory by default. Compiled
417   sources will be placed in the ```bin_test``` directory. Can be overridden
418   with the ```testsrc``` and ```testbin``` Bnd settings respectively.
419
420 * Output directory ```generated```. Built OSGi bundles will be placed here.
421   Can be overridden with the ```target-dir``` Bnd setting
422
423
424 # <a name="BuildFlow"/>Build Flow
425
426 Understanding the build flow is especially important if the build must be
427 modified: extra tasks must be added, properties must be overridden, etc.
428
429 The build has the following flow:
430
431 * <a name="BuildProperties"/>Gradle loads all properties defined in
432   the ```gradle.properties``` file in the root of the workspace.
433
434   This file is used to bootstrap the build and (among other things) defines
435   the build dependencies:
436
437   * All ```*.uri``` settings are considered to be build dependencies.
438
439     An ```example.uri``` setting will make the build script add the file
440     indicated by the URI to the build dependencies when the file exists on
441     the local filesystem. If the file doesn't exist on the local filesystem,
442     then the build script will download the build dependency from the
443     specified URI into the ```cnf/cache``` directory and add it to the build
444     dependencies.
445
446     **Note**: Using a ```*.uri``` setting that points to an external location
447     is **not recommended** since the build will then no longer be
448     self-contained (because it needs network access).
449
450 * Gradle invokes the ```settings.gradle``` file in the root of the workspace.
451   This file initialises the build:
452
453   * Detect the location of the configuration project
454     (see [Configuration Project](#ProjectsAndWorkspacesCnf)).
455
456   * Initialise the Bnd workspace.
457
458   * The build dependencies are determined from the build properties that
459     were loaded from the ```gradle.properties``` file
460     (see [the explanation of the build properties file](#BuildProperties).
461
462   * Include all **Bnd** projects and all **Gradle** projects
463     (see [Sub-Projects](#ProjectsAndWorkspacesSubProjects) for an
464     explanation).
465
466 * Gradle invokes the ```build.gradle``` file from the root project. This
467   file sets up the build:
468
469   * The Bnd plugin is loaded.
470
471   * The hook ```cnf/gradle/custom/workspace-pre.gradle``` is invoked.
472
473   * The rest of the build template basically has 3 sections which are applied
474     in the order:
475
476     * All projects
477     * Sub-Projects
478     * Root Project
479
480     **All Projects**
481
482     This section sets up the build for all included projects (including the
483     root project) by iterating over all included projects and performing the
484     actions described below.
485
486     * The Gradle build directory of the project is set to the Bnd
487       default (```generated```).
488
489     * The hook ```cnf/gradle/custom/allProject-pre.gradle``` is invoked.
490
491     * If the project has project specific build settings in
492       a ```build-settings.gradle``` file in its project root directory then
493       the file is invoked.
494
495       Project specific build settings allow - on a project-by-project basis -
496       overrides of the build settings, additions to the build, modifications
497       of the build, etc.
498
499     * Clean tasks are added to the project.
500
501     * The hook ```cnf/gradle/custom/allProject-post.gradle``` is invoked.
502
503     **Sub-Projects**
504
505     This section sets up the build for all included projects, (excluding the
506     root project) by iterating over all included sub-projects. In the
507     iteration a distinction is made between **Bnd** projects and **Gradle**
508     projects.
509
510     * The hook ```cnf/gradle/custom/subProject-pre.gradle``` is invoked.
511
512     * Gradle projects (Non-Bnd Projects)
513
514       * The hook ```cnf/gradle/custom/nonBndProject-pre.gradle``` is invoked.
515
516       * The default tasks are setup (specified by the ```others_defaultTask```
517         property). This is a comma separated list of task names.
518
519     * Bnd projects
520
521       * The Bnd project instance is stored in the project as
522         the ```bndProject``` property.
523
524       * The hook ```cnf/gradle/custom/bndProject-pre.gradle``` is invoked.
525
526       * The Bnd plugin is applied.
527
528       * The javadoc bootclasspath is adjusted to include the bootclasspath
529         of the Bnd project.
530
531       * The hook ```cnf/gradle/custom/bndProject-post.gradle``` is invoked.
532
533     * All projects that have applied the Gradle Java plugin (which includes
534       Bnd projects):
535
536       * The hook ```cnf/gradle/custom/javaProject-pre.gradle``` is invoked.
537
538       * The javaDoc task is setup.
539
540       * The findbugs tasks are setup.
541
542       * The jacoco task is setup.
543
544       * The clean task is adjusted to clean all output directories of all
545         sourceSets.
546
547       * The hook ```cnf/gradle/custom/javaProject-post.gradle``` is invoked.
548
549     * The hook ```cnf/gradle/custom/subProject-post.gradle``` is invoked.
550
551     **Root Project**
552
553     This section sets up the build (defaults) for the root project.
554
555     * The hook ```cnf/gradle/custom/rootProject-pre.gradle``` is invoked.
556
557     * The default tasks are setup (specified by the ```root_defaultTask```
558       property).  This is a comma separated list of task names.
559
560     * The wrapper task is setup.
561
562     * The distclean task is adjusted to also clean the ```cnf/cache```
563       and ```.gradle``` directories.
564
565     * The hook ```cnf/gradle/custom/rootProject-post.gradle``` is invoked.
566
567   * The hook ```cnf/gradle/custom/workspace-post.gradle``` is invoked.
568
569 * For every included project with a ```build.gradle``` build script, Gradle
570   invokes that build script.
571
572 * Gradle resolves the build setup.
573
574 * Gradle now builds the projects by running the specified (or default) tasks.
575
576
577 # <a name="BuildTasks"/>Build Tasks
578
579 The discussion of the build tasks below is split per project type.
580
581
582 ## <a name="BuildTasksBndProjects"/>Bnd Projects
583
584 This section only discusses tasks that are added or modified compared to the
585 Gradle Java plugin.
586
587
588 ### <a name="BuildTasksJar"/>jar
589
590 This task instructs Bnd to construct the project's OSGi bundles. The bundles
591 are placed in the project's ```generated``` directory.
592
593 This is comparable to the ```jar``` task that is defined by the Java plugin,
594 which instructs the Java compiler to construct a standard jar. However, a
595 Bnd project completely replaces that ```jar``` task.
596
597 The ```bnd.bnd``` file describes how the OSGi bundle(s) must be constructed
598 and is therefore taken as input by Bnd.
599
600 This task is automatically disabled when no bundle(s) must be contructed.
601
602
603 ### <a name="BuildTasksTestOSGi"/>testOSGi
604
605 This task instructs Bnd to run bundle OSGi (integration) tests.
606
607 This is comparable to the ```test``` task that is defined by the Java plugin,
608 which instructs the Java runtime to run unit tests.
609
610 Refer to the Bnd manual/website for more details on how to setup bundle tests.
611
612 Set ```check.ignoreFailures = true``` on the project to not fail the build
613 on test failures.
614
615 This task is automatically disabled when no bundle tests have been defined.
616
617
618 ### <a name="BuildTasksCheck"/>check
619
620 This task instructs Bnd to run all tests.
621
622 Set ```check.ignoreFailures = true``` on the project to not fail the build
623 on check failures.
624
625
626 ### <a name="BuildTasksCheckNeeded"/>checkNeeded
627
628 This task will invoke the ```check``` task on all projects on which the
629 project is dependent, after which the ```check``` task is invoked on the
630 project itself.
631
632
633 ### <a name="BuildTasksRelease"/>release
634
635 This task instructs Bnd to copy the constructed OSGi bundle into the release
636 repository.
637
638 This task is automatically disabled when no release repository is defined or
639 when no bundle(s) must be constructed.
640
641
642 ### <a name="BuildTasksReleaseNeeded"/>releaseNeeded
643
644 This task will invoke the ```release``` task on all projects on which the
645 project is dependent, after which the ```release``` task is invoked on the
646 project itself.
647
648
649 ### <a name="BuildTasksRunBundlesName"/>runbundles.<name>
650
651 This task will copy all runbundles metioned in the ``<name>.bndrun``` file in
652 the project to a distribution directory. The bundles are place in the
653 directory ```generated/distributions/runbundles/<name>```.
654
655 This task is only setup if the project contains a ```<name>.bndrun``` file.
656
657
658 ### <a name="BuildTasksRunbundles"/>runbundles
659
660 This task will invoke the ```runbundles.<name>``` for all ```*.bndrun```
661 files in the project.
662
663 This task is automatically disabled when the project contains
664 no ```*.bndrun``` files.
665
666
667 ### <a name="BuildTasksExportName"/>export.<name>
668
669 This task will export the ```<name>.bndrun``` file in the project to an
670 executable jar. The executable jar is placed in the
671 project's ```generated/distributions``` directory as ```<name>.jar```.
672
673 This task is only setup if the project contains a ```<name>.bndrun``` file.
674
675
676 ### <a name="BuildTasksExport"/>export
677
678 This task will export all ```*.bndrun``` files in the project to executable
679 jars.
680
681 This task is automatically disabled when the project contains
682 no ```*.bndrun``` files.
683
684
685 ### <a name="BuildTasksResolveName"/>resolve.<name>
686
687 This task will resolve the ```<name>.bndrun``` file in the project 
688 and update the ```-runbundles``` instruction in the file.
689
690 This task is only setup if the project contains a ```<name>.bndrun``` file.
691
692
693 ### <a name="BuildTasksResolve"/>resolve
694
695 This task will resolves all ```*.bndrun``` files in the project and update
696 their ```-runbundles``` instructions.
697
698 This task is automatically disabled when the project contains
699 no ```*.bndrun``` files.
700
701
702 ### <a name="BuildTasksRunName"/>run.<name>
703
704 This task will run the ```<name>.bndrun``` file in the project.
705
706 This task is only setup if the project contains a ```<name>.bndrun``` file.
707
708
709 ### <a name="BuildTasksTestRunName"/>testrun.<name>
710
711 This task will run the OSGi JUnit tests in the ```<name>.bndrun``` file in
712 the project.
713
714 This task is only setup if the project contains a ```<name>.bndrun``` file.
715
716
717 ### <a name="BuildTasksEcho"/>echo
718
719 This task displays some key Bnd properties of the project.
720
721
722 ### <a name="BuildTasksBndProperties"/>bndproperties
723
724 This task - analogous to the Gradle ```properties``` task - displays the Bnd
725 properties that are defined for the project.
726
727 These properties are defined in the ```bnd.bnd``` file in the root of the
728 project (and optionally other ```*.bnd``` files when using the ```-sub```
729 instruction for sub-bundles).
730
731 Properties that are defined in workspace-wide ```*.bnd``` files that are
732 loaded from the configuration project (```cnf```) are also displayed as they
733 obviously also apply to the project (unless overridden by the project, in
734 which case the overridden values are shown).
735
736
737 ### <a name="BuildTasksClean"/>clean
738
739 This task instructs Bnd to clean up the project, which removes
740 the output directory and the directories that hold the class files.
741
742 This is in addition to the ```clean``` task that is defined by the Java plugin.
743
744
745 ### <a name="BuildTasksCleanNeeded"/>cleanNeeded
746
747 This task will invoke the ```clean``` task on all projects on which the
748 project is dependent, after which the ```clean``` task is invoked on the
749 project itself.
750
751
752 ## <a name="BuildTasksAllProjects"/>All Projects
753
754 This section discusses tasks that are added to all projects.
755
756
757 ### <a name="BuildTasksAllClean"/>clean
758
759 This (empty) task is only added to the project when it doesn't yet have
760 a ```clean``` task. The reason for this is to be able to easily declare clean
761 task dependencies.
762
763
764 ### <a name="BuildTasksAllCleanNeeded"/>cleanNeeded
765
766 This (empty) task is only added to the project when it doesn't yet have
767 a ```cleanNeeded``` task. The reason for this is to be able to easily declare
768 clean task dependencies.
769
770
771 ### <a name="BuildTasksDistClean"/>distClean
772
773 This (empty by default) task is meant to perform additional cleanup compared
774 to the ```clean``` task.
775
776 The build adjusts this task for the root project such that it removes:
777
778 * The cache directory in the configuration project.
779
780 * The Gradle cache directory.
781
782
783 ### <a name="BuildTasksDistCleanNeeded"/>distcleanNeeded
784
785 This task will invoke the ```distClean``` task on all projects on which the
786 project is dependent, after which the ```distClean``` task is invoked on the
787 project itself.
788
789
790 ## <a name="BuildTasksJavaProjects"/>Java Projects
791
792 This section discusses tasks that are added to all Java projects (which
793 includes Bnd projects).
794
795
796 ### <a name="BuildTasksFindbugs"/>Findbugs
797
798 The findbugs plugin is applied to all Java projects. This plugin adds the
799 tasks ```findbugsMain``` and ```findbugsTest```.
800
801 These two tasks are disabled by default since running findbugs is an
802 expensive operation and is not needed for most builds. Enabling these tasks
803 is discussed below.
804
805 **Note**: The reports that are generated by the findbugs tasks will only have
806 line numbers when the tasks are run on a build that produces artefacts with
807 debug information.
808
809 #### <a name="BuildTasksFindbugsMain"/>findbugsMain
810
811 This task will run findbugs on the main source code.
812
813 #### <a name="BuildTasksFindbugsTest"/>findbugsTest
814
815 This task will run findbugs on the test source code.
816
817 #### <a name="BuildTasksfindbugs"/>findbugs
818
819 Specifying this (virtual) task will **enable** the ```findbugsMain``` task.
820
821 **Note**: It is still required to specify a task that has a dependency on
822 the ```findbugsMain``` task to actually run it. The tasks ```check```
823 and ```build``` are examples of such a task.
824
825 #### <a name="BuildTasksfindbugstest"/>findbugstest
826
827 Specifying this (virtual) task will **enable** the ```findbugsTest``` task.
828
829 **Note**: it is still required to specify a task that has a dependency on
830 the ```findbugsTest``` task to actually run it. The tasks ```check```
831 and ```build``` are examples of such a task.
832
833 #### <a name="FindbugsSettings"/>Settings
834
835 * &nbsp;```findbugsReportXML```: The name of the property that must be defined
836                                  in order to generate XML reports instead of
837                                  HTML reports (since the findbugs plugin can't
838                                  create them both at the same time). Defaults
839                                  to **CI**.
840
841 * &nbsp;```findbugsIgnoreFailures```: **true** to ignore findbugs warning (to
842                                       **not** fail the build). Defaults
843                                       to **true**.
844
845 * &nbsp;```findbugsIncludesFile```: The file with include rules. Defaults
846                                     to ```${rootProject.rootDir}/${rootProject.bnd_cnf}/findbugs/findbugs.include.xml```.
847
848 * &nbsp;```findbugsExcludesFile```: The file with exclude rules. Defaults
849                                     to ```{rootProject.rootDir}/${rootProject.bnd_cnf}/findbugs/findbugs.exclude.xml```.
850
851 The defaults for the settings can be overridden by defining the settings in
852 the project's ```build-settings.gradle``` file.
853
854
855 ### <a name="BuildTasksJacoco"/>Jacoco
856
857 The jacoco plugin is applied to all Java projects. This plugin adds the
858 task ```jacocoTestReport``` which details the test coverage.
859
860 The ```jacocoTestReport``` task is automatically run when either or both of
861 the ```test``` and ```check``` tasks are scheduled to run.
862
863 An ```test.exec``` report - for consumption by a build server - is always
864 created.
865
866 #### <a name="BuildTasksJacocoSettings"/>Settings
867
868 * &nbsp;```jacocoToolVersion```: The version of the jacoco plugin to use.
869                                  Defaults to **0.7.5.201505241946**.
870
871 * &nbsp;```jacocoXmlReport```: **true** to generate XML reports. Defaults
872                                to **true**.
873
874 * &nbsp;```jacocoCsvReport```: **true** to generate CSV reports. Defaults
875                                to **false**.
876
877 The defaults for the settings can be overridden by defining the settings in
878 the project's ```build-settings.gradle``` file.
879
880
881 ### <a name="BuildTasksJavadoc"/>javadoc
882
883 This task generates javadoc for the main source code.
884
885 #### <a name="BuildTasksJavadocSettings"/>Settings
886
887 * &nbsp;```javadocDir```: The directory (relative to the project's build
888                           directory) in which to place the javadoc.
889                           Defaults to **javadoc**.
890
891 * &nbsp;```javadocTitle```: The same as ```javadocDocTitle```.
892                             Defaults to **${project.name}**.
893
894 * &nbsp;```javadocFailOnError```: **false** to ignore errors (to **not** fail
895                                   the build).
896                                   Defaults to **true**.
897
898 * &nbsp;```javadocMaxMemory```: The maximum amount of memory that the javadoc
899                                 task is allowed to consume.
900                                 Defaults to **256M**.
901
902 * &nbsp;```javadocVerbose```: **true** for verbose mode: provide more
903                               detailed messages while javadoc is running.
904                               Without the verbose option, messages appear for
905                               loading the source files, generating the
906                               documentation (one message per source file),
907                               and sorting. The verbose option causes the
908                               printing of additional messages specifying the
909                               number of milliseconds to parse each java
910                               source file.
911                               Defaults to **false**.
912
913 * &nbsp;```javadocDocTitle```: The title to be placed near the top of the
914                                overview summary file. The title will be placed
915                                as a centered, level-one heading directly
916                                beneath the upper navigation bar. The title may
917                                contain html tags and white space, though if it
918                                does, it must be enclosed in quotes. Any
919                                internal quotation marks within title may have
920                                to be escaped.
921                                Defaults to **${project.name}**.
922
923 * &nbsp;```javadocWindowTitle```:  The title to be placed in the
924                                    HTML ```<title>``` tag. This appears in the
925                                    window title and in any browser bookmarks
926                                    (favorite places) that someone creates for
927                                    this page. This title should not contain
928                                    any HTML tags, as the browser will not
929                                    properly interpret them. Any internal
930                                    quotation marks within title may have to
931                                    be escaped.
932                                    Defaults to **${project.name}**.
933
934 * &nbsp;```javadocClassPathBoot```: The bootclasspath.
935                                     Defaults to an empty list of files.
936                                     Is automatically set for Bnd projects.
937
938 * &nbsp;```javadocMemberLevel```: The minimum member level to include in the
939                                   generated documention. Can be (from lowest
940                                   level to highest level): **PRIVATE**
941                                   , **PROTECTED**, **PACKAGE**, **PUBLIC**.
942                                   Defaults to **PUBLIC**.
943
944 * &nbsp;```javadocEncoding```: The encoding name of the source files.
945                                Defaults to **UTF-8**.
946
947 * &nbsp;```javadocAuthor```: **true** to include the @author text in the
948                              generated documentation.
949                              Defaults to **true**.
950
951 * &nbsp;```javadocBreakIterator```: **true** to use the internationalized
952                                     sentence boundary of
953                                     java.text.BreakIterator to determine the
954                                     end of the first sentence for English
955                                     (all other locales already use
956                                     BreakIterator), rather than an English
957                                     language, locale-specific algorithm. By
958                                     first sentence, the first sentence in the
959                                     main description of a package, class or
960                                     member is meant. This sentence is copied
961                                     to the package, class or member summary,
962                                     and to the alphabetic index.
963                                     Defaults to **true**.
964
965 * &nbsp;```javadocDocFilesSubDirs```: **true** to enable deep copying
966                                       of "doc-files" directories. In other
967                                       words, subdirectories and all contents
968                                       are recursively copied to the
969                                       destination. For example, the
970                                       directory ```doc-files/example/images```
971                                       and all its contents would now be copied.
972                                       Defaults to **true**.
973
974 * &nbsp;```javadocNoComment```: **true** to suppress the entire comment body,
975                                 including the main description and all tags,
976                                 generating only declarations. This option
977                                 enables re-using source files originally
978                                 intended for a different purpose, to produce
979                                 skeleton HTML documentation at the early
980                                 stages of a new project.
981                                 Defaults to **false**.
982
983 * &nbsp;```javadocNoDeprecated```: **true** to prevent the generation of any
984                                    deprecated API at all in the documentation.
985                                    This does what ```javadocNoDeprecatedList```
986                                    does, plus it does not generate any
987                                    deprecated API throughout the rest of the
988                                    documentation. This is useful when writing
989                                    code and you don't want to be distracted
990                                    by the deprecated code.
991                                    Defaults to **false**.
992
993 * &nbsp;```javadocNoDeprecatedList```: **true** to prevent the generation of
994                                        the file containing the list of
995                                        deprecated APIs (deprecated-list.html)
996                                        and the link in the navigation bar to
997                                        that page. (However, javadoc continues
998                                        to generate the deprecated API
999                                        throughout the rest of the document.)
1000                                        This is useful if your source code
1001                                        contains no deprecated API, and you
1002                                        want to make the navigation bar cleaner.
1003                                        Defaults to **false**.
1004
1005 * &nbsp;```javadocNoHelp```: **true** to omit the HELP link in the navigation
1006                              bars at the top and bottom of each page of output. 
1007                              Defaults to **false**.
1008
1009 * &nbsp;```javadocNoIndex```: **true** to omit the index from the generated
1010                               documentation. The index is produced by default.
1011                               Defaults to **false**.
1012
1013 * &nbsp;```javadocNoNavBar```: **true** to prevent the generation of the
1014                                navigation bar, header and footer, otherwise
1015                                found at the top and bottom of the generated
1016                                pages. Has no effect on the "bottom" option.
1017                                The option is useful when you are interested
1018                                only in the content and have no need for
1019                                navigation, such as converting the files to
1020                                PostScript or PDF for print only.
1021                                Defaults to **false**.
1022
1023 * &nbsp;```javadocNoSince```: **true** to omit from the generated documentation
1024                               the "Since" sections associated with the @since
1025                               tags.
1026                               Defaults to **false**.
1027
1028 * &nbsp;```javadocNoTimestamp```: **true** to suppress the timestamp, which
1029                                   is hidden in an HTML comment in the generated
1030                                   HTML near the top of each page. Useful when
1031                                   you want to run javadoc on two source bases
1032                                   and diff them, as it prevents timestamps
1033                                   from causing a diff (which would otherwise
1034                                   be a diff on every page). The timestamp
1035                                   includes the javadoc version number.
1036                                   Defaults to **false**.
1037
1038 * &nbsp;```javadocNoTree```: **true** to omit the class/interface hierarchy
1039                              pages from the generated documentation. These
1040                              are the pages you reach using the "Tree" button
1041                              in the navigation bar.
1042                              Defaults to **false**.
1043
1044 * &nbsp;```javadocSplitIndex```: **true** to split the index file into
1045                                  multiple files, alphabetically, one file per
1046                                  letter, plus a file for any index entries
1047                                  that start with non-alphabetical characters.
1048                                  Defaults to **true**.
1049
1050 * &nbsp;```javadocUse```: **true** to include one "Use" page for each
1051                           documented class and package. The page describes
1052                           what packages, classes, methods, constructors and
1053                           fields use any API of the given class or package.
1054                           Given class C, things that use class C would
1055                           include subclasses of C, fields declared as C,
1056                           methods that return C, and methods and constructors
1057                           with parameters of type C. You can access the
1058                           generated "Use" page by first going to the class or
1059                           package, then clicking on the "Use" link in the
1060                           navigation bar.
1061                           Defaults to **true**.
1062
1063 * &nbsp;```javadocVersion```: **true** to include the @version text in the
1064                               generated documentation.
1065                               Defaults to **true**.
1066
1067 The defaults for the settings can be overridden by defining the settings in
1068 the project's ```build-settings.gradle``` file.
1069
1070
1071 ### <a name="BuildTasksJavaClean"/>clean
1072
1073 The build adjusts this task for Java projects (which includes Bnd projects)
1074 such that it removes:
1075
1076 * The class files output directory of all defined sourcesets.
1077
1078 * The resources output directory of all defined sourcesets.
1079
1080
1081 ## <a name="BuildTasksRootProject"/>Root Project
1082
1083 This section discusses tasks that are modified for the root project.
1084
1085 ### <a name="BuildTasksWrapper"/>wrapper
1086
1087 This task downloads Gradle and installs it in the workspace,
1088 see [Installing Gradle In The Workspace](#InstallingGradleInTheWorkspace).
1089
1090
1091 #### <a name="BuildTasksRootProjectSettings"/>Settings
1092
1093 * &nbsp;```rootGradleVersion```: The version of the Gradle to use when
1094                                  generating the Gradle wrapper.
1095                                  Not setting it will result in the latest
1096                                  released version of Gradle being used.
1097                                  No default.
1098
1099 The defaults for the settings can be overridden by defining the settings in
1100 the project's ```build-settings.gradle``` file.
1101
1102
1103 # <a name="BuildOptions"/>Build Options
1104
1105
1106 ## <a name="BuildOptionsBndProjects"/>Bnd Projects
1107
1108 * The ```jar``` task can be disabled by:
1109
1110   * Presence of the ```-nobundles``` instruction in the ```bnd.bnd``` file.
1111
1112 * The ```test``` task can be disabled by:
1113
1114   * Presence of the ```-nojunit``` instruction in the ```bnd.bnd``` file.
1115
1116   * Presence of the ```no.junit```  property in the ```bnd.bnd``` file.
1117
1118 * The ```check``` task can be disabled by:
1119
1120   * Presence of the ```-nojunitosgi``` instruction in the ```bnd.bnd``` file.
1121
1122   * Absence of the ```Test-Cases``` Bnd property in the ```bnd.bnd``` file.
1123
1124 * The ```release``` task can be disabled by:
1125
1126   * Presence of the ```-nobundles``` instruction in the ```bnd.bnd``` file.
1127
1128   * Absence of the ```-releaserepo``` instruction in any of the Bnd files.
1129
1130
1131 ## <a name="BuildOptionsFindbugs"/>Findbugs
1132
1133 The findbugs tasks will - by default - generate HTML reports, but can be
1134 instructed to generate XML reports by setting the ```CI``` Gradle system
1135 property (```-PCI``` on the command line).
1136
1137 &nbsp;```CI``` = **C**ontinous **I**ntegration
1138                  (since XML reports are typically used on build servers)
1139
1140
1141 # <a name="CustomisingTheBuild"/>Customising The Build
1142
1143
1144 ## <a name="CustomisingTheBuildGradle"/>Gradle
1145
1146 The build be can easily customised by putting overrides and additions in any
1147 of the ```cnf/gradle/custom/*.gradle``` build script hook files,
1148 see [Build Flow](#BuildFlow).
1149
1150 Also, any project can - on an individual basis - customise build settings or
1151 specify additions by placing a ```build-settings.gradle``` file in its
1152 root directory.
1153
1154 The ```build-settings.gradle``` file is meant for settings and settings
1155 overrides, the ```build.gradle``` file is meant for tasks.
1156
1157
1158 ## <a name="CustomisingTheBuildBnd"/>Bnd
1159
1160 The Bnd default settings are shown in the ```cnf/build.bnd``` file.
1161 Overrides to workspace-wide Bnd settings can be placed in that same file.
1162
1163 If a setting must be overridden or defined for a specific project, then that
1164 setting must be defined in the ```bnd.bnd``` file of that specific project.
1165
1166
1167 # <a name="AddingJavaProjectsToTheBuild"/>Adding Java Projects To The Build
1168
1169 The build automatically includes all Bnd projects.
1170
1171 However, regular Java projects are not included automatically:
1172 a ```build.gradle``` file or a ```build-settings.gradle``` file in the root
1173 directory of the project is needed to make that happen.
1174
1175 Such projects only need to apply the Gradle Java plugin, setup their
1176 sourceSets, and setup their build directory. The template will then
1177 automatically apply the
1178 buildscript ```cnf/gradle/template/javaProject.gradle``` which adds tasks
1179 that are relevant to Java projects,
1180 see [Java Projects](#BuildTasksJavaProjects).
1181
1182 The ```build-settings.gradle``` file shown below can be used as the basis.
1183 This will setup the Java project with the default Bnd layout and add tasks
1184 that are relevant to a Java project (```javadoc```, ```findbugs...```, etc.).
1185
1186 ```
1187 /*
1188  * A java project with Bnd layout
1189  */
1190
1191 assert(project != rootProject)
1192
1193 apply plugin: 'java'
1194
1195 /* We use the same directory for java and resources. */
1196 sourceSets {
1197   main {
1198     java.srcDirs      = resources.srcDirs   = files('src')
1199     output.classesDir = output.resourcesDir =       'bin'
1200   }
1201   test {
1202     java.srcDirs        = resources.srcDirs   = files('test'    )
1203     output.classesDir   = output.resourcesDir =       'test_bin'
1204   }
1205 }
1206
1207 buildDir = 'generated'
1208 ```
1209
1210 The ```build-settings.gradle``` file shown below can be used as the basis for a
1211 project with the Maven layout.
1212
1213 ```
1214 /*
1215  * A java project with Maven layout
1216  */
1217
1218 assert(project != rootProject)
1219
1220 apply plugin: 'java'
1221
1222 /* We do not use the same directory for java and resources. */
1223 sourceSets {
1224   main {
1225     java.srcDirs        = files('src/main/java'     )
1226     resources.srcDirs   = files('src/main/resources')
1227     output.classesDir   =       'target/classes'
1228     output.resourcesDir =       'target/classes'
1229   }
1230   test {
1231     java.srcDirs        = files('src/test/java'     )
1232     resources.srcDirs   = files('src/test/resources')
1233     output.classesDir   =       'target/test-classes'
1234     output.resourcesDir =       'target/test-classes'
1235   }
1236 }
1237
1238 buildDir = 'target'
1239 ```
1240
1241
1242 # <a name="BuildIndexing"/>OSGi Repository Indexing
1243
1244 Indexing a tree of bundles to generate an OSGi repository index is now
1245 handled through Bnd's Index task,
1246 see [Bnd's README](https://github.com/bndtools/bnd/blob/master/biz.aQute.bnd.gradle/README.md#create-a-task-of-the-index-type).
1247
1248 As an example, say you'd want to create a (compressed) repository index of all
1249 the bundles in the directory ```cnf/somerepo```. You would then create or
1250 adjust the file ```cnf/build.gradle``` and add something like below:
1251
1252 ```
1253 import aQute.bnd.gradle.Index
1254
1255 task index(type: Index) {
1256    destinationDir = file('somerepo')
1257    gzip = true
1258    indexName = "your-custom-index.xml"
1259    repositoryName = "You Custom Index Name"
1260    bundles = fileTree(destinationDir) {
1261     include '**/*.jar'
1262     exclude '**/*-latest.jar'
1263     exclude '**/*-sources.jar'
1264     exclude '**/*-javadoc.jar'
1265   }
1266 }
1267 ```
1268
1269
1270 # <a name="JenkinsBuildSetup"/>Jenkins Build Setup
1271
1272 The screenshot ([Jenkins-Build-Settings.jpg](Jenkins-Build-Settings.jpg)) shows
1273 part of an example job.
1274
1275 The shown settings can be used as an example, but can slightly differ for your
1276 own builds.
1277
1278 The following Jenkins plugins should be installed to take advantage of the
1279 various functionalities of the build (some of which are shown in the
1280 screenshot):
1281
1282 * build timeout plugin
1283 * build-name-setter
1284 * FindBugs Plug-in
1285 * Git Parameter Plug-In
1286 * GIT plugin
1287 * Gradle plugin
1288 * JaCoCo plugin
1289 * Javadoc Plugin
1290 * JUnit Plugin
1291 * Mailer Plugin
1292
1293 Ensure your Jenkins has the most recent versions of these plugins.
1294
1295 This applies especially to the Jacoco plugin since the binary format of Jacoco
1296 was changed a few times in the second half of 2015.
1297