INSTALL.md 5.39 KB
Newer Older
Tobias Wich's avatar
Tobias Wich committed
1
2
3
4
5
6
Prerequisites
=============

In order to build the Open eCard project, some additional tools are needed.

Required dependencies are:
7
8
9
* Java JDK 11 or higher - Oracle JDK and OpenJDK are working correctly (jlink is required for building modular runtime images)

* Maven in at least version 3.6.1
Tobias Wich's avatar
Tobias Wich committed
10
11
12
13

  https://maven.apache.org/download.html

* Git 1.7.11 or higher (older versions are probably also ok)
14

Tobias Wich's avatar
Tobias Wich committed
15
16
17
  http://git-scm.com/downloads

Optional dependencies are:
18
19
20
21
* Java JDK 14 with the new jpackage tool for creating native packages (early-access builds are available)

  https://jdk.java.net/jpackage/)

Tobias Wich's avatar
Tobias Wich committed
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
* Android SDK
  The Android SDK dependent modules are built when the environment variable
  ANDROID_HOME is set and points to the installation directory of the Android
  SDK.

  https://developer.android.com/sdk/index.html

* Android NDK
  The Android NDK dependent modules are built when the environment variable
  ANDROID_NDK_HOME is set and points to the installation directory of the
  Android NDK. The Android NDK has a direct dependency for the Android
  SDK. However due to restrictions in maven, no actual check is performed
  enforcing that the Android SDK must also be configured.

  https://developer.android.com/tools/sdk/ndk/index.html

38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
Native packages can be created with an early-access build of JDK-14 which contains the new jpackage tool. For this purpose, JDK-14 must be managed independently of other JDK versions. This can be done with Maven toolchains. For this purpose, a `toolchains.xml` file is required on the building machine. The default location of this file is `~/.m2/toolchains.xml`. It should look similar to this one (JDK paths must be 	adjusted):

```xml
<?xml version="1.0" encoding="UTF8"?>
<toolchains>
	<!-- JDK toolchains -->
        <toolchain>
                <type>jdk</type>
                <provides>
                        <version>14</version>
                        <vendor>OpenJDK</vendor>
                        <id>JavaSE-14</id>
                </provides>
                <configuration>
			<jdkHome>/usr/lib/jvm/jdk-14/</jdkHome>
                </configuration>
        </toolchain>
        <toolchain>
                <type>jdk</type>
                <provides>
                        <version>11</version>
                        <vendor>OpenJDK</vendor>
                        <id>JavaSE-11</id>
                </provides>
                <configuration>
			<jdkHome>/usr/lib/jvm/java-11-openjdk-amd64/</jdkHome>
                </configuration>
        </toolchain>
</toolchains>
```

If native packages are not created on the building machine, the first toolchain is not required.
Tobias Wich's avatar
Tobias Wich committed
70
71
72
73
74
75

Build Sources
=============

A standard build is performed by the command:

76
    $ mvn clean install
Tobias Wich's avatar
Tobias Wich committed
77
78
79

In order to create Javadoc and source artifacts, perform the following command:

80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
    $ mvn clean javadoc:javadoc javadoc:jar source:jar install

By default, only a modular runtime image is created. However, if the early-access build of JDK-14 with the new jpackage tool is added to the toolchains, a native application package can be created by using the property `desktop-package`:

    $ mvn clean install -Ddesktop-package

Usually, the predefined package formats are used: dmg for Mac OS, deb for Linux and msi and exe for Windows. An additional property `jlink-jpackager.package-type` can replace the predefined format of the native application package (only for Mac and Linux). The possible formats are:

 - dmg
 - pkg
 - deb
 - rpm

A native package with the `pkg` format can be created by using the following command:

    $ mvn clean install -Ddesktop-package -Djlink-jpackager.package-type=pkg

The developer has to make sure that all necessary packaging tools are installed. In case of Windows, msi and exe packages are built. For this purpose, two additional tools are required:
Tobias Wich's avatar
Tobias Wich committed
98

99
100
 - [WiX toolset](https://wixtoolset.org/) - to create msi installers
 - [Inno Setup](http://www.jrsoftware.org/isinfo.php) - to create exe installers (Path environment variable must be set)
Tobias Wich's avatar
Tobias Wich committed
101
102
103
104
105
106
107
108
109
110

Build Profiles
--------------

The Open eCard project uses Maven profiles to modify how the build is
performed and which artifacts are created.

Maven profiles are selected on the commandline by adding the -P option as
follows:

111
    $ mvn -Pprofile1,profile2 <Maven goals>
Tobias Wich's avatar
Tobias Wich committed
112
113
114
115
116
117
118
119
120
121
122
123
124


The following global profiles are defined:
* `release`
  Remove debugging symbols from Java bytecode.

The following profiles are module specific:

Module `clients/applet`
* `trace-applet`
  Bundle SLF4J extension artifact, so that the applet can emit trace logs.

Module `clients/richclient`
125
126
127
* `bundles-jar-cifs`
  Usually the cifs are provided by a seperate artifact. This profile creates
  a 'contains everything' jar file for direct execution.
Tobias Wich's avatar
Tobias Wich committed
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151


Code Signing
------------

The `applet` and `richclient` modules produce signed artifacts. A dummy
certificate is included in the source distribution, so the build runs in any
case. If another certificate from a trusted CA should be used, then the
following fragment must be inserted into `$HOME/.m2/settings.xml`:

  <profiles>
    <profile>
      <id>override-sign</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <sign.keystore>PATH_TO_JAVA_KEYSTORE</sign.keystore>
        <sign.storepass>KEYSTORE_PASSWORD</sign.storepass>
        <sign.keypass>CERTIFICATE_KEY_PASSWORD</sign.keypass>
        <sign.alias>CERTIFICATE_ALIAS</sign.alias>
      </properties>
    </profile>
  </profiles>