summaryrefslogtreecommitdiffstats
path: root/solenv/maven
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--solenv/maven/BUCK44
-rw-r--r--solenv/maven/README.md384
-rw-r--r--solenv/maven/VERSION7
-rwxr-xr-xsolenv/maven/mvn.py78
-rw-r--r--solenv/maven/package.defs28
5 files changed, 541 insertions, 0 deletions
diff --git a/solenv/maven/BUCK b/solenv/maven/BUCK
new file mode 100644
index 000000000..fd1252df0
--- /dev/null
+++ b/solenv/maven/BUCK
@@ -0,0 +1,44 @@
+include_defs('//solenv/maven/VERSION')
+include_defs('//solenv/maven/package.defs')
+
+URL = 'https://oss.sonatype.org/content/repositories/snapshots' \
+ if LIBREOFFICE_VERSION.endswith('-SNAPSHOT') else \
+ 'https://oss.sonatype.org/service/local/staging/deploy/maven2'
+
+maven_package(
+ repository = 'sonatype-nexus-staging',
+ url = URL,
+ version = LIBREOFFICE_VERSION,
+ jar = {
+ 'juh': '//:juh',
+ 'jurt': '//:jurt',
+ 'officebean': '//:officebean',
+ 'ridl': '//:ridl',
+ 'unoil': '//:unoil',
+ 'unoloader': '//:unoloader',
+ 'libreoffice': '//:libreoffice',
+ },
+ src = {
+ 'juh': '//javaunohelper:juh-src',
+ 'jurt': '//jurt:jurt-src',
+ 'officebean': '//bean:officebean-src',
+ 'ridl': '//ridljar:ridl-src',
+ 'unoil': '//unoil:unoil-src',
+ 'unoloader': '//ridljar/source/unoloader:unoloader-src',
+ 'libreoffice': '//ridljar:libreoffice-src',
+ },
+ doc = {
+ 'juh': '//javaunohelper:juh-javadoc',
+ 'jurt': '//jurt:jurt-javadoc',
+ 'officebean': '//bean:officebean-javadoc',
+ 'ridl': '//ridljar:ridl-javadoc',
+ 'unoil': '//unoil:unoil-javadoc',
+ 'unoloader': '//ridljar/source/unoloader:unoloader-javadoc',
+ 'libreoffice': '//ridljar:libreoffice-javadoc',
+ },
+)
+
+python_binary(
+ name = 'mvn',
+ main = 'mvn.py',
+)
diff --git a/solenv/maven/README.md b/solenv/maven/README.md
new file mode 100644
index 000000000..0b19cd2fe
--- /dev/null
+++ b/solenv/maven/README.md
@@ -0,0 +1,384 @@
+= Uploading LibreOffice API to Maven Central
+
+This file documents the prerequisites and workflow to upload LibreOffice
+API to Maven Central or local Maven repository.
+
+To install LibreOffice API to local Maven repository or deploy the API
+to the Maven Central, extra build toolchain is required.
+
+`Ant` is used to bootstrap `Buck` build tool. `Buck` build tool is
+used to build sources and javadocs for the API and install or deploy
+the artifacts to Maven repository. `Maven` commands are invoked for
+that from within `Buck` driven build - so make sure you've maven
+installed, too. To be able to upload the API to Maven Central, access
+must be granted to LibreOffice project on OSSRH.
+
+
+== Buck
+
+`Buck` is new build tool that uses Python to write build files. It is
+maintained by Facebook and is available under Apache 2 license.
+
+
+=== Installing Buck
+
+There is currently no binary distribution of `Buck`, so it has to be manually
+built and installed. Apache Ant and gcc are required.
+
+Clone the git and build it:
+
+----
+ git clone https://github.com/facebook/buck
+ cd buck
+ ant
+----
+
+If you don't have a `bin/` directory in your home directory, create one:
+
+----
+ mkdir ~/bin
+----
+
+Add the `~/bin` folder to the path:
+
+----
+ PATH=~/bin:$PATH
+----
+
+Note that the buck executable needs to be available in all shell sessions,
+so also make sure it is appended to the path globally.
+
+Add a symbolic link in `~/bin` to the buck and buckd executables:
+
+----
+ ln -s `pwd`/bin/buck ~/bin/
+ ln -s `pwd`/bin/buckd ~/bin/
+----
+
+Verify that `buck` is accessible:
+
+----
+ which buck
+----
+
+To enable autocompletion of buck commands, install the autocompletion
+script from `./scripts/buck_completion.bash` in the buck project. Refer
+to the script's header comments for installation instructions.
+
+
+=== Prerequisites
+
+Buck requires Python version 2.7 to be installed. The Maven download toolchain
+requires `curl` to be installed.
+
+
+=== Using Buck daemon
+
+Buck ships with a daemon command `buckd`, which uses the
+link:https://github.com/martylamb/nailgun[Nailgun] protocol for running
+Java programs from the command line without incurring the JVM startup
+overhead.
+
+Using a Buck daemon can save significant amounts of time as it avoids the
+overhead of starting a Java virtual machine, loading the buck class files
+and parsing the build files for each command.
+
+It is safe to run several buck daemons started from different project
+directories and they will not interfere with each other. Buck's documentation
+covers daemon in http://facebook.github.io/buck/command/buckd.html[buckd].
+
+To use `buckd` the additional
+link:https://facebook.github.io/watchman[watchman] program must be installed.
+
+To disable `buckd`, the environment variable `NO_BUCKD` must be set. It's not
+recommended to put it in the shell config, as it can be forgotten about it and
+then assumed Buck was working as it should when it should be using buckd.
+Prepend the variable to Buck invocation instead:
+
+----
+ NO_BUCKD=1 buck build api
+----
+
+
+=== Installing watchman
+
+Watchman is used internally by Buck to monitor directory trees and is needed
+for buck daemon to work properly. Because buckd is activated by default in the
+latest version of Buck, it searches for the watchman executable in the
+path and issues a warning when it is not found and kills buckd.
+
+To prepare watchman installation on Linux:
+
+----
+ git clone https://github.com/facebook/watchman.git
+ cd watchman
+ ./autogen.sh
+----
+
+To install it in user home directory (without root privileges):
+
+----
+ ./configure --prefix $HOME/watchman
+ make install
+----
+
+To install it system wide:
+
+----
+ ./configure
+ make
+ sudo make install
+----
+
+Put $HOME/watchman/bin/watchman in path or link to $HOME/bin/watchman.
+
+To install watchman on macOS:
+
+----
+ brew install --HEAD watchman
+----
+
+See the original documentation for more information:
+link:https://facebook.github.io/watchman/docs/install.html[Watchman
+installation].
+
+
+=== Override Buck's settings
+
+Additional JVM args for Buck can be set in `.buckjavaargs` in the
+project root directory. For example to override Buck's default 1GB
+heap size:
+
+----
+ cat > .buckjavaargs <<EOF
+ -XX:MaxPermSize=512m -Xms8000m -Xmx16000m
+ EOF
+----
+
+
+== Preparations to publish LibreOffice API to Maven Central
+
+
+=== Deploy Configuration settings for Maven Central
+
+
+To be able to publish artifacts to Maven Central some preparations must
+be done:
+
+* Create an account on
+link:https://issues.sonatype.org/secure/Signup!default.jspa[Sonatype's Jira].
+
+Sonatype is the company that runs Maven Central and you need a Sonatype
+account to be able to upload artifacts to Maven Central.
+
+* Configure your Sonatype user and password in `~/.m2/settings.xml`:
+
+----
+<settings>
+ <servers>
+ <server>
+ <id>sonatype-nexus-staging</id>
+ <username>USER</username>
+ <password>PASSWORD</password>
+ </server>
+ </servers>
+</settings>
+----
+
+* Request permissions to upload artifacts to the `org.libreoffice`
+repository on Maven Central:
+
+Ask for this permission by adding a comment on the
+link:https://issues.sonatype.org/browse/OSSRH-19129[OSSRH-19129] Jira
+ticket at Sonatype.
+
+The request needs to be approved by someone who already has this
+permission by commenting on the same issue.
+
+* Generate and publish a PGP key
+
+Generate and publish a PGP key as described in
+link:http://central.sonatype.org/pages/working-with-pgp-signatures.html[
+Working with PGP Signatures].
+
+Please be aware that after publishing your public key it may take a
+while until it is visible to the Sonatype server.
+
+The PGP key is needed to be able to sign the artifacts before the
+upload to Maven Central.
+
+The PGP passphrase can be put in `~/.m2/settings.xml`, or
+alternatively make gpg use the agent to provide and cache the
+credentials:
+
+----
+<settings>
+ <profiles>
+ <profile>
+ <id>gpg</id>
+ <properties>
+ <gpg.executable>gpg2</gpg.executable>
+ <gpg.passphrase>mypassphrase</gpg.passphrase>
+ <gpg.keyname>mykeynameoremail</gpg.keyname>
+ <gpg.useAgent>true</gpg.useAgent>
+ </properties>
+ </profile>
+ </profiles>
+ <activeProfiles>
+ <activeProfile>gpg</activeProfile>
+ </activeProfiles>
+</settings>
+----
+
+It can also be included in the key chain on macOS.
+
+
+== Update Versions
+
+Before publishing new artifacts to Maven Central, `LIBREOFFICE_VERSION`
+in the `VERSION` file must be updated, e.g. change it from `5.0.0` to `5.1.0`.
+
+In addition the version must be updated in a number of pom.xml files.
+
+To do this run the `./solenv/bin/version.py` script and provide the new
+version as parameter, e.g.:
+
+----
+ ./solenv/bin/version.py 5.1.0
+----
+
+
+== Build LibreOffice
+
+Build LibreOffice as usually, so that API JARs are created.
+
+
+== Publish the LibreOffice artifacts to local Maven repository
+
+Execute this command to install LibreOffice API to your local Maven
+repository. For troubleshooting, the environment variable `VERBOSE`
+can be set:
+
+----
+ VERBOSE=1 buck build api_install
+----
+
+Once executed, the local Maven repository contains the LibreOffice API
+artifacts:
+
+----
+ $ ls -1 ~/.m2/repository/org/libreoffice/unoil/5.1.0/
+ _maven.repositories
+ unoil-5.1.0.jar
+ unoil-5.1.0-javadoc.jar
+ unoil-5.1.0.pom
+ unoil-5.1.0-sources.jar
+----
+
+
+== Publish the LibreOffice artifacts to Maven Central
+
+* Make sure you have done the configuration for deploying to Maven Central.
+* Make sure that the version is updated in the `VERSION` file and in
+the `pom.xml` files as described above.
+
+Push the API to Maven Central:
+
+----
+ buck build api_deploy
+----
+
+For troubleshooting, the environment variable `VERBOSE` can be set. This
+prints out the commands that are executed by the Buck build process:
+
+----
+ VERBOSE=1 buck build api_deploy
+----
+
+If no artifacts are uploaded, clean the `buck-out` folder and retry:
+
+----
+ rm -rf buck-out
+----
+
+* To where the artifacts are uploaded depends on the `LIBREOFFICE_VERSION`
+in the `VERSION` file:
+
+** SNAPSHOT versions are directly uploaded into the Sonatype snapshots
+repository and no further action is needed:
+
+https://oss.sonatype.org/content/repositories/snapshots/org/libreoffice/
+
+** Release versions are uploaded into a staging repository in the
+link:https://oss.sonatype.org/[Sonatype Nexus Server].
+
+* Verify the staging repository
+
+** Go to the link:https://oss.sonatype.org/[Sonatype Nexus Server] and
+sign in with your Sonatype credentials.
+
+** Click on 'Build Promotion' in the left navigation bar under
+'Staging Repositories' and find the `orglibreoffice-XXXX` staging
+repository.
+
+** Verify its content
+
+While the staging repository is open you can upload further content and
+also replace uploaded artifacts. If something is wrong with the staging
+repository you can drop it by selecting it and clicking on `Drop`.
+
+** Run Sonatype validations on the staging repository
+
+Select the staging repository and click on `Close`. This runs the
+Sonatype validations on the staging repository. The repository will
+only be closed if everything is OK. A closed repository cannot be
+modified anymore, but you may still drop it if you find any issues.
+
+** Test closed staging repository
+
+Once a repository is closed you can find the URL to it in the `Summary`
+section, e.g. https://oss.sonatype.org/content/repositories/orglibreoffice-4711
+
+Use this URL for further testing of the artifacts in this repository,
+e.g. to try building an extension against this API in this repository
+update the version in the `pom.xml` and configure the repository:
+
+----
+ <repositories>
+ <repository>
+ <id>mexus-staging-repository</id>
+ <url>https://oss.sonatype.org/content/repositories/orglibreoffice-4711</url>
+ </repository>
+ </repositories>
+----
+
+* Release the staging repository
+
+How to release a staging repository is described in the
+link:https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide#SonatypeOSSMavenRepositoryUsageGuide-8.a.2.ReleasingaStagingRepository[
+Sonatype OSS Maven Repository Usage Guide].
+
+[WARNING]
+Releasing artifacts to Maven Central cannot be undone!
+
+** Find the closed staging repository in the
+link:https://oss.sonatype.org/[Sonatype Nexus Server], select it and
+click on `Release`.
+
+** The released artifacts are available in
+https://oss.sonatype.org/content/repositories/releases/org/libreoffice/
+
+** It may take up to 2 hours until the artifacts appear on Maven
+Central:
+
+http://central.maven.org/maven2/org/libreoffice/
+
+* [optional]: View download statistics
+
+** Sign in to the
+link:https://oss.sonatype.org/[Sonatype Nexus Server].
+
+** Click on 'Views/Repositories' in the left navigation bar under
+'Central Statistics'.
+
+** Select `org.libreoffice` as `Project`.
diff --git a/solenv/maven/VERSION b/solenv/maven/VERSION
new file mode 100644
index 000000000..c99b63d49
--- /dev/null
+++ b/solenv/maven/VERSION
@@ -0,0 +1,7 @@
+# Maven style API version (e.g. '2.x-SNAPSHOT').
+#
+# Used by :install and :deploy when talking to the destination repository. As
+# we currently have no stable releases, we use the "build number" scheme
+# described at:
+# http://mojo.codehaus.org/versions-maven-plugin/version-rules.html
+LIBREOFFICE_VERSION = '@version@'
diff --git a/solenv/maven/mvn.py b/solenv/maven/mvn.py
new file mode 100755
index 000000000..5b45447da
--- /dev/null
+++ b/solenv/maven/mvn.py
@@ -0,0 +1,78 @@
+#!/usr/bin/python
+# This file is part of the LibreOffice project.
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from __future__ import print_function
+from optparse import OptionParser
+from os import path, environ
+from subprocess import check_output
+from sys import stderr
+
+M = {
+ 'juh': 'javaunohelper',
+ 'jurt': 'jurt',
+ 'officebean': 'bean',
+ 'ridl': 'ridljar',
+ 'unoil': 'unoil',
+ 'unoloader': 'ridljar',
+ 'libreoffice': 'ridljar',
+}
+
+opts = OptionParser()
+opts.add_option('--repository', help='maven repository id')
+opts.add_option('--url', help='maven repository url')
+opts.add_option('-o')
+opts.add_option('-a', help='action (valid actions are: install,deploy)')
+opts.add_option('-v', help='gerrit version')
+opts.add_option('-s', action='append', help='triplet of artifactId:type:path')
+
+args, ctx = opts.parse_args()
+if not args.v:
+ print('version is empty', file=stderr)
+ exit(1)
+
+root = path.abspath(__file__)
+while not path.exists(path.join(root, '.buckconfig')):
+ root = path.dirname(root)
+
+if 'install' == args.a:
+ cmd = [
+ 'mvn',
+ 'install:install-file',
+ '-Dversion=%s' % args.v,
+ ]
+elif 'deploy' == args.a:
+ cmd = [
+ 'mvn',
+ 'gpg:sign-and-deploy-file',
+ '-DrepositoryId=%s' % args.repository,
+ '-Durl=%s' % args.url,
+ ]
+else:
+ print("unknown action -a %s" % args.a, file=stderr)
+ exit(1)
+
+for spec in args.s:
+ artifact, packaging_type, src = spec.split(':')
+ exe = cmd + [
+ '-DpomFile=%s' % path.join(root, '%s/pom.%s.xml' % (M[artifact], artifact)),
+ '-Dpackaging=%s' % packaging_type,
+ '-Dfile=%s' % src,
+ ]
+ try:
+ if environ.get('VERBOSE'):
+ print(' '.join(exe), file=stderr)
+ check_output(exe)
+ except Exception as e:
+ print('%s command failed: %s' % (args.a, e), file=stderr)
+ exit(1)
+
+with open(args.o, 'w') as fd:
+ if args.repository:
+ print('Repository: %s' % args.repository, file=fd)
+ if args.url:
+ print('URL: %s' % args.url, file=fd)
+ print('Version: %s' % args.v, file=fd)
diff --git a/solenv/maven/package.defs b/solenv/maven/package.defs
new file mode 100644
index 000000000..2c67d8fe9
--- /dev/null
+++ b/solenv/maven/package.defs
@@ -0,0 +1,28 @@
+def maven_package(
+ version,
+ repository = None,
+ url = None,
+ jar = {},
+ src = {},
+ doc = {}):
+ cmd = ['$(exe //solenv/maven:mvn)', '-v', version, '-o', '$OUT']
+ api_cmd = []
+ for type,d in [('jar', jar), ('java-source', src), ('javadoc', doc)]:
+ for a,t in d.iteritems():
+ api_cmd.append('-s %s:%s:$(location %s)' % (a,type,t))
+
+ genrule(
+ name = 'api_install',
+ cmd = ' '.join(cmd + api_cmd + ['-a', 'install']),
+ out = 'api_install.info',
+ )
+
+ if repository and url:
+ genrule(
+ name = 'api_deploy',
+ cmd = ' '.join(cmd + api_cmd + [
+ '-a', 'deploy',
+ '--repository', repository,
+ '--url', url]),
+ out = 'api_deploy.info',
+ )