solenv/maven/README.md

   1 = Uploading LibreOffice API to Maven Central
   2
   3 This file documents the prerequisites and workflow to upload LibreOffice
   4 API to Maven Central or local Maven repository.
   5
   6 To install LibreOffice API to local Maven repository or deploy the API
   7 to the Maven Central, extra build toolchain is required.
   8
   9 `Ant` is used to bootstrap `Buck` build tool. `Buck` build tool is
  10 used to build sources and javadocs for the API and install or deploy
  11 the artifacts to Maven repository. `Maven` commands are invoked for
  12 that from within `Buck` driven build - so make sure you've maven
  13 installed, too. To be able to upload the API to Maven Central, access
  14 must be granted to LibreOffice project on OSSRH.
  15
  16
  17 == Buck
  18
  19 `Buck` is new build tool that uses Python to write build files. It is
  20 maintained by Facebook and is available under Apache 2 license.
  21
  22
  23 === Installing Buck
  24
  25 There is currently no binary distribution of `Buck`, so it has to be manually
  26 built and installed. Apache Ant and gcc are required.
  27
  28 Clone the git and build it:
  29
  30 ----
  31   git clone https://github.com/facebook/buck
  32   cd buck
  33   ant
  34 ----
  35
  36 If you don't have a `bin/` directory in your home directory, create one:
  37
  38 ----
  39   mkdir ~/bin
  40 ----
  41
  42 Add the `~/bin` folder to the path:
  43
  44 ----
  45   PATH=~/bin:$PATH
  46 ----
  47
  48 Note that the buck executable needs to be available in all shell sessions,
  49 so also make sure it is appended to the path globally.
  50
  51 Add a symbolic link in `~/bin` to the buck and buckd executables:
  52
  53 ----
  54   ln -s `pwd`/bin/buck ~/bin/
  55   ln -s `pwd`/bin/buckd ~/bin/
  56 ----
  57
  58 Verify that `buck` is accessible:
  59
  60 ----
  61   which buck
  62 ----
  63
  64 To enable autocompletion of buck commands, install the autocompletion
  65 script from `./scripts/buck_completion.bash` in the buck project.  Refer
  66 to the script's header comments for installation instructions.
  67
  68
  69 === Prerequisites
  70
  71 Buck requires Python version 2.7 to be installed. The Maven download toolchain
  72 requires `curl` to be installed.
  73
  74
  75 === Using Buck daemon
  76
  77 Buck ships with a daemon command `buckd`, which uses the
  78 link:https://github.com/martylamb/nailgun[Nailgun] protocol for running
  79 Java programs from the command line without incurring the JVM startup
  80 overhead.
  81
  82 Using a Buck daemon can save significant amounts of time as it avoids the
  83 overhead of starting a Java virtual machine, loading the buck class files
  84 and parsing the build files for each command.
  85
  86 It is safe to run several buck daemons started from different project
  87 directories and they will not interfere with each other. Buck's documentation
  88 covers daemon in http://facebook.github.io/buck/command/buckd.html[buckd].
  89
  90 To use `buckd` the additional
  91 link:https://facebook.github.io/watchman[watchman] program must be installed.
  92
  93 To disable `buckd`, the environment variable `NO_BUCKD` must be set. It's not
  94 recommended to put it in the shell config, as it can be forgotten about it and
  95 then assumed Buck was working as it should when it should be using buckd.
  96 Prepend the variable to Buck invocation instead:
  97
  98 ----
  99   NO_BUCKD=1 buck build api
 100 ----
 101
 102
 103 === Installing watchman
 104
 105 Watchman is used internally by Buck to monitor directory trees and is needed
 106 for buck daemon to work properly. Because buckd is activated by default in the
 107 latest version of Buck, it searches for the watchman executable in the
 108 path and issues a warning when it is not found and kills buckd.
 109
 110 To prepare watchman installation on Linux:
 111
 112 ----
 113   git clone https://github.com/facebook/watchman.git
 114   cd watchman
 115   ./autogen.sh
 116 ----
 117
 118 To install it in user home directory (without root privileges):
 119
 120 ----
 121   ./configure --prefix $HOME/watchman
 122   make install
 123 ----
 124
 125 To install it system wide:
 126
 127 ----
 128   ./configure
 129   make
 130   sudo make install
 131 ----
 132
 133 Put $HOME/watchman/bin/watchman in path or link to $HOME/bin/watchman.
 134
 135 To install watchman on macOS:
 136
 137 ----
 138   brew install --HEAD watchman
 139 ----
 140
 141 See the original documentation for more information:
 142 link:https://facebook.github.io/watchman/docs/install.html[Watchman
 143 installation].
 144
 145
 146 === Override Buck's settings
 147
 148 Additional JVM args for Buck can be set in `.buckjavaargs` in the
 149 project root directory. For example to override Buck's default 1GB
 150 heap size:
 151
 152 ----
 153   cat > .buckjavaargs <<EOF
 154   -XX:MaxPermSize=512m -Xms8000m -Xmx16000m
 155   EOF
 156 ----
 157
 158
 159 == Preparations to publish LibreOffice API to Maven Central
 160
 161
 162 === Deploy Configuration settings for Maven Central
 163
 164
 165 To be able to publish artifacts to Maven Central some preparations must
 166 be done:
 167
 168 * Create an account on
 169 link:https://issues.sonatype.org/secure/Signup!default.jspa[Sonatype's Jira].
 170
 171 Sonatype is the company that runs Maven Central and you need a Sonatype
 172 account to be able to upload artifacts to Maven Central.
 173
 174 * Configure your Sonatype user and password in `~/.m2/settings.xml`:
 175
 176 ----
 177 <settings>
 178   <servers>
 179     <server>
 180      <id>sonatype-nexus-staging</id>
 181      <username>USER</username>
 182      <password>PASSWORD</password>
 183    </server>
 184   </servers>
 185 </settings>
 186 ----
 187
 188 * Request permissions to upload artifacts to the `org.libreoffice`
 189 repository on Maven Central:
 190
 191 Ask for this permission by adding a comment on the
 192 link:https://issues.sonatype.org/browse/OSSRH-19129[OSSRH-19129] Jira
 193 ticket at Sonatype.
 194
 195 The request needs to be approved by someone who already has this
 196 permission by commenting on the same issue.
 197
 198 * Generate and publish a PGP key
 199
 200 Generate and publish a PGP key as described in
 201 link:http://central.sonatype.org/pages/working-with-pgp-signatures.html[
 202 Working with PGP Signatures].
 203
 204 Please be aware that after publishing your public key it may take a
 205 while until it is visible to the Sonatype server.
 206
 207 The PGP key is needed to be able to sign the artifacts before the
 208 upload to Maven Central.
 209
 210 The PGP passphrase can be put in `~/.m2/settings.xml`, or
 211 alternatively make gpg use the agent to provide and cache the
 212 credentials:
 213
 214 ----
 215 <settings>
 216   <profiles>
 217     <profile>
 218       <id>gpg</id>
 219       <properties>
 220         <gpg.executable>gpg2</gpg.executable>
 221         <gpg.passphrase>mypassphrase</gpg.passphrase>
 222         <gpg.keyname>mykeynameoremail</gpg.keyname>
 223         <gpg.useAgent>true</gpg.useAgent>
 224       </properties>
 225     </profile>
 226   </profiles>
 227   <activeProfiles>
 228     <activeProfile>gpg</activeProfile>
 229   </activeProfiles>
 230 </settings>
 231 ----
 232
 233 It can also be included in the key chain on macOS.
 234
 235
 236 == Update Versions
 237
 238 Before publishing new artifacts to Maven Central, `LIBREOFFICE_VERSION`
 239 in the `VERSION` file must be updated, e.g. change it from `5.0.0` to `5.1.0`.
 240
 241 In addition the version must be updated in a number of pom.xml files.
 242
 243 To do this run the `./solenv/bin/version.py` script and provide the new
 244 version as parameter, e.g.:
 245
 246 ----
 247   ./solenv/bin/version.py 5.1.0
 248 ----
 249
 250
 251 == Build LibreOffice
 252
 253 Build LibreOffice as usually, so that API JARs are created.
 254
 255
 256 == Publish the LibreOffice artifacts to local Maven repository
 257
 258 Execute this command to install LibreOffice API to your local Maven
 259 repository. For troubleshooting, the environment variable `VERBOSE`
 260 can be set:
 261
 262 ----
 263   VERBOSE=1 buck build api_install
 264 ----
 265
 266 Once executed, the local Maven repository contains the LibreOffice API
 267 artifacts:
 268
 269 ----
 270   $ ls -1 ~/.m2/repository/org/libreoffice/unoil/5.1.0/
 271   _maven.repositories
 272   unoil-5.1.0.jar
 273   unoil-5.1.0-javadoc.jar
 274   unoil-5.1.0.pom
 275   unoil-5.1.0-sources.jar
 276 ----
 277
 278
 279 == Publish the LibreOffice artifacts to Maven Central
 280
 281 * Make sure you have done the configuration for deploying to Maven Central.
 282 * Make sure that the version is updated in the `VERSION` file and in
 283 the `pom.xml` files as described above.
 284
 285 Push the API to Maven Central:
 286
 287 ----
 288   buck build api_deploy
 289 ----
 290
 291 For troubleshooting, the environment variable `VERBOSE` can be set. This
 292 prints out the commands that are executed by the Buck build process:
 293
 294 ----
 295   VERBOSE=1 buck build api_deploy
 296 ----
 297
 298 If no artifacts are uploaded, clean the `buck-out` folder and retry:
 299
 300 ----
 301   rm -rf buck-out
 302 ----
 303
 304 * To where the artifacts are uploaded depends on the `LIBREOFFICE_VERSION`
 305 in the `VERSION` file:
 306
 307 ** SNAPSHOT versions are directly uploaded into the Sonatype snapshots
 308 repository and no further action is needed:
 309
 310 https://oss.sonatype.org/content/repositories/snapshots/org/libreoffice/
 311
 312 ** Release versions are uploaded into a staging repository in the
 313 link:https://oss.sonatype.org/[Sonatype Nexus Server].
 314
 315 * Verify the staging repository
 316
 317 ** Go to the link:https://oss.sonatype.org/[Sonatype Nexus Server] and
 318 sign in with your Sonatype credentials.
 319
 320 ** Click on 'Build Promotion' in the left navigation bar under
 321 'Staging Repositories' and find the `orglibreoffice-XXXX` staging
 322 repository.
 323
 324 ** Verify its content
 325
 326 While the staging repository is open you can upload further content and
 327 also replace uploaded artifacts. If something is wrong with the staging
 328 repository you can drop it by selecting it and clicking on `Drop`.
 329
 330 ** Run Sonatype validations on the staging repository
 331
 332 Select the staging repository and click on `Close`. This runs the
 333 Sonatype validations on the staging repository. The repository will
 334 only be closed if everything is OK. A closed repository cannot be
 335 modified anymore, but you may still drop it if you find any issues.
 336
 337 ** Test closed staging repository
 338
 339 Once a repository is closed you can find the URL to it in the `Summary`
 340 section, e.g. https://oss.sonatype.org/content/repositories/orglibreoffice-4711
 341
 342 Use this URL for further testing of the artifacts in this repository,
 343 e.g. to try building an extension against this API in this repository
 344 update the version in the `pom.xml` and configure the repository:
 345
 346 ----
 347   <repositories>
 348     <repository>
 349       <id>mexus-staging-repository</id>
 350       <url>https://oss.sonatype.org/content/repositories/orglibreoffice-4711</url>
 351     </repository>
 352   </repositories>
 353 ----
 354
 355 * Release the staging repository
 356
 357 How to release a staging repository is described in the
 358 link:https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide#SonatypeOSSMavenRepositoryUsageGuide-8.a.2.ReleasingaStagingRepository[
 359 Sonatype OSS Maven Repository Usage Guide].
 360
 361 [WARNING]
 362 Releasing artifacts to Maven Central cannot be undone!
 363
 364 ** Find the closed staging repository in the
 365 link:https://oss.sonatype.org/[Sonatype Nexus Server], select it and
 366 click on `Release`.
 367
 368 ** The released artifacts are available in
 369 https://oss.sonatype.org/content/repositories/releases/org/libreoffice/
 370
 371 ** It may take up to 2 hours until the artifacts appear on Maven
 372 Central:
 373
 374 http://central.maven.org/maven2/org/libreoffice/
 375
 376 * [optional]: View download statistics
 377
 378 ** Sign in to the
 379 link:https://oss.sonatype.org/[Sonatype Nexus Server].
 380
 381 ** Click on 'Views/Repositories' in the left navigation bar under
 382 'Central Statistics'.
 383
 384 ** Select `org.libreoffice` as `Project`.