diff options
Diffstat (limited to 'solenv/maven')
| -rw-r--r-- | solenv/maven/BUCK | 44 | ||||
| -rw-r--r-- | solenv/maven/README.md | 384 | ||||
| -rw-r--r-- | solenv/maven/VERSION | 7 | ||||
| -rwxr-xr-x | solenv/maven/mvn.py | 78 | ||||
| -rw-r--r-- | solenv/maven/package.defs | 28 |
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', + ) |