Adding upstream version 4:24.2.0.upstream/4%24.2.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

5 files changed, 541 insertions, 0 deletions

diff --git a/solenv/maven/BUCK b/solenv/maven/BUCK
new file mode 100644
index 0000000000..fd1252df0c
--- /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 0000000000..0b19cd2fe8
--- /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 0000000000..c99b63d49f
--- /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 0000000000..5b45447daa
--- /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 0000000000..2c67d8fe9d
--- /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',
+    )