1AusweisApp2
2===========
3
4Kontakt
5-------
6| Governikus GmbH & Co. KG
7| Hochschulring 4
8| 28359 Bremen
9| support@ausweisapp.de
10
11
12Lizenz
13------
14Der vorliegende Quellcode wird unter der EUPL v1.2 bereitgestellt, mit
15Ausnahme der Bibliothek OpenSSL, die unter der OpenSSL License / SSLeay License
16lizensiert ist. Die Datei ``LICENSE.officially.txt`` gilt ausschließlich für
17die offizielle Version der AusweisApp2, welche von der Governikus GmbH & Co. KG
18im Auftrag des Bundes unter https://www.ausweisapp.bund.de bereitgestellt wird.
19
20
21Toolchain / Bibliotheken
22------------------------
23Die Einrichtung der Toolchain wird im Unterordner ``./libs``
24bzw. in der darin enthaltenen README erläutert.
25
26Die separate README und das Skript unter "libs" dienen dem Aufzusetzen
27der notwendigen Build-Umgebung und dem automatisierten Bauen der
28notwendigen Bibliotheken mit den entsprechenden Patches.
29
30
31
32Build
33-----
34Um die AusweisApp2 zu bauen ist es notwendig ein Makefile mittels CMake zu
35generieren. Dazu kann CMake auf der Kommandozeile oder mit der von CMake
36mitgelieferten CMake-GUI ausgeführt werden.
37
38CMake erkennt während der Konfigurationszeit automatisch die Abhängigkeiten.
39Dazu kann die Variable *CMAKE_PREFIX_PATH* verwendet werden um die Toolchain CMake
40bekannt zu machen. Alternativ zu %PATH% bzw. $PATH können alle Ordner, die dort
41für den Build eingetragen wurden, über diesen Mechanismus an CMake übergeben werden.
42
43Als Generator für Makefiles sollte unter Windows eine Variante von "MinGW Makefiles"
44gewählt werden.
45
46Beim Generieren des Makefiles ist zu beachten, dass die AusweisApp2 nur sogenannte
47"out of source tree"-Builds erlaubt. Daher ist die empfohlene Variante von CMake
48zwingend einzuhalten und der Build-Ordner darf sich nicht im Source-Ordner
49befinden.
50
51Beispiel über die CLI:
52
53::
54
55   C:/AusweisApp2/
56   C:/Toolchain/
57   C:/build/
58
59::
60
61   $ cd C:/build
62   $ cmake -G "MinGW Makefiles" -DCMAKE_PREFIX_PATH=C:/Toolchain ../AusweisApp2 -DCMAKE_BUILD_TYPE=release
63   -- The CXX compiler identification is GNU 4.9.1
64   -- Check for working CXX compiler: C:/mingw32/bin/g++.exe
65   -- Check for working CXX compiler: C:/mingw32/bin/g++.exe -- works
66   -- Detecting CXX compiler ABI info
67   -- Detecting CXX compiler ABI info - done
68   -- VERSION: 1.0.0
69   -- CMAKE_INSTALL_PREFIX: C:/build/dist
70   -- CMAKE_BUILD_TYPE: RELEASE
71   -- CMAKE_PREFIX_PATH: C:/Toolchain
72   -- CMAKE_INCLUDE_PATH:
73   -- CMAKE_LIBRARY_PATH:
74   -- CMAKE_SYSTEM_PREFIX_PATH: C:\Program Files;C:\Program Files (x86);C:/Program Files (x86)/CMake;C:/Program Files (x86)/AusweisApp2
75   -- CMAKE_SYSTEM_INCLUDE_PATH:
76   -- BUILD_SHARED_LIBS: OFF
77   -- Found OpenSSL: C:/Toolchain/lib/libssl.dll.a;C:/Toolchain/lib/libcrypto.dll.a (found suitable version "1.0.1i", minimum required is "1.0.1")
78   -- Found Hg: C:/Program Files/TortoiseHg/hg.exe (found version "3.1.1")
79   -- Configuring done
80   -- Generating done
81   -- Build files have been written to: C:/build
82
83
84Um die mobile Variante der AusweisApp2 zu bauen benötigt man je nach Plattform zusätzliche
85externe Komponenten, die in der README in ``./libs`` im Abschnitt Android / iOS beschrieben
86sind.
87
88
89
90Android
91^^^^^^^
92Bei Android ist zu beachten, dass ein CMAKE_TOOLCHAIN_FILE angegeben werden muss.
93
94::
95
96   $ cd build
97   $ cmake -DCMAKE_PREFIX_PATH=/home/governikus/Toolchain/dist -DCMAKE_TOOLCHAIN_FILE=../AusweisApp2/cmake/android.toolchain.cmake ../AusweisApp2
98   $ make
99   $ make install
100   $ make apk
101
102Unter dem Ordner "./dist/bin" ist nun ein "AusweisApp2...apk" erstellt worden.
103
104Sofern der Parameter *CMAKE_BUILD_TYPE* auf RELEASE gesetzt wird, sind folgende CMake
105Parameter notwendig um das APK zu signieren.
106
107::
108
109   -DAPK_SIGN_KEYSTORE=/home/governikus/ausweisapp2.apk.keystore.jks
110   -DAPK_SIGN_KEYSTORE_ALIAS=ausweisapp
111   -DAPK_SIGN_KEYSTORE_PSW=123456
112
113Wie schon bei der Toolchain wird standardmäßig die Architektur "armeabi-v7a" verwendet.
114Dies kann mittels CMake Parameter "-DCMAKE_ANDROID_ARCH_ABI=x86" verändert werden.
115
116
117
118iOS
119^^^
120Bei iOS wird ein Bundle gebaut, welches mit einem zusätzlichen Befehl in eine IPA-Datei
121eingebettet werden kann. Zu beachten ist vor allem, dass in der Umgebungsvariable
122*PROVISIONING_PROFILE* das jeweilige Profil verwendet wird, welches unter XCode
123eingerichtet ist. Im Ordner "~/Library/MobileDevice/Provisioning Profiles"
124sind diese ebenfalls einsehbar.
125Unter Umständen kann es zu Berechtigungsproblemen mit XCode und den Zugriff auf
126die Keys kommen. Dabei ist es oft hilfreich die Keys im macOS-Schlüsselbund
127freizuschalten bzw. den Schlüsselbund freizugeben.
128
129security unlock-keychain -pPASSWORD ${HOME}/Library/Keychains/login.keychain
130
131Für iOS wird die AusweisApp2 mittels XCode gebaut!
132
133::
134
135   $ cd build
136   $ cmake -DCMAKE_PREFIX_PATH=/Users/governikus/Toolchain/dist -DCMAKE_TOOLCHAIN_FILE=../AusweisApp2/cmake/iOS.toolchain.cmake -DCMAKE_BUILD_TYPE=MinSizeRel ../AusweisApp2 -GXcode
137   $ xcodebuild -configuration MinSizeRel -archivePath AusweisApp2.xcarchive -scheme AusweisApp archive
138   $ xcodebuild -configuration MinSizeRel -archivePath AusweisApp2.xcarchive -exportArchive -exportOptionsPlist exportOptions.plist -exportPath .
139
140
141Im Build-Ordner befindet sich nun ein *.ipa und ein *.xcarchive, welches jeweils das
142signierte Bundle enthält!
143
144
145
146Packages
147--------
148Nachdem die Build-Umgebung eingerichtet ist, kann je nach System ein Package erstellt werden.
149
150- Unter Windows ist hierfür noch das WiX Toolset (http://wixtoolset.org/ Getestet: 3.8 bis 3.10)
151  notwendig.
152  Mittels "mingw32-make package" wird die AusweisApp2 gebaut und ein MSI Paket bereitgestellt.
153
154- Unter macOS wird mittels "make package" die AusweisApp2 gebaut und ein DMG bereitgestellt.
155
156- Um ein APK für Android zu bauen, sind zwei Schritte notwendig, da CMake das Format bisher
157  nicht unterstützt. Daher sind nach der Konfiguration des Projektes folgende Befehle notwendig
158  um ein endgültiges APK zu erhalten:
159
160  ::
161
162     $ make install
163     $ make apk
164
165
166
167Reproduzierbarer Build
168----------------------
169Wir sind stets bemüht den Build des offiziellen Binaries der AusweisApp2 nachvollziehbar zu gestalten.
170Daher haben wir unter anderem eine README in dem Unterordner ``./libs`` hinterlegt, die den Aufbau
171der Buildumgebung und den Build der externen Bibliotheken beschreibt.
172Anhand dieser Anleitung können Sie nachvollziehen, wie unser internes Buildsystem aufgebaut ist und
173welche Compiler bzw. Compiler-Versionen wir verwenden.
174
175Im Unterordner ``./resources/jenkins/`` ist es möglich, unsere Konfiguration des CI-Servers einzusehen.
176Die Konfiguration besteht aus mehreren Dockerfiles und JobDSL-Dateien.
177
178Anhand dieser Skripte ist es möglich, den Build der AusweisApp2 zu reproduzieren.
179Ein Unterschied zum offiziellen Binary sollte lediglich in eventuellen Pfaden,
180einem Datum bzw. Zeitstempel und Signaturen bestehen.
181
182.. seealso::
183  https://reproducible-builds.org/
184