From 8e96485a87faf2cb03559096346264280a37e47e Mon Sep 17 00:00:00 2001 From: Philip Kuryloski Date: Fri, 13 Nov 2020 15:01:21 +0100 Subject: [PATCH] Move (copy) the README file back into place Recent commits which vendor all of the various rabbitmq-components into this repository moved the root README file to another location. It has some relevancy at that location, so we copy it back to the root. --- README.md | 328 ++++++--------------------------------------- SERVER_RELEASES.md | 313 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 353 insertions(+), 288 deletions(-) create mode 100644 SERVER_RELEASES.md diff --git a/README.md b/README.md index 41cfec6285ae..28bb2699fda9 100644 --- a/README.md +++ b/README.md @@ -1,313 +1,65 @@ -# RabbitMQ server releases +[![OTP v22.3](https://img.shields.io/github/workflow/status/rabbitmq/rabbitmq-server/Test%20-%20Erlang%2022.3/master?label=Erlang%2022.3)](https://github.com/rabbitmq/rabbitmq-server/actions?query=workflow%3A%22Test+-+Erlang+22.3%22+branch%3A%22master%22) +[![OTP v23](https://img.shields.io/github/workflow/status/rabbitmq/rabbitmq-server/Test%20-%20Erlang%2023.1/master?label=Erlang%2023.1)](https://github.com/rabbitmq/rabbitmq-server/actions?query=workflow%3A%22Test+-+Erlang+23.1%22+branch%3Amaster) -This repository provides scripts and Makefiles we use to create RabbitMQ -server releases. It is organized in the following way: -* The top-level `Makefile` manages the source archive. -* There is a subdirectory inside `packaging` for each type of package we - support. +# RabbitMQ Server -## TL;DR +[RabbitMQ](https://rabbitmq.com) is a [feature rich](https://rabbitmq.com/documentation.html), multi-protocol messaging broker. It supports: -* To create a source archive and all supported packages: + * AMQP 0-9-1 + * AMQP 1.0 + * MQTT 3.1.1 + * STOMP 1.0 through 1.2 - ``` - make packages - ``` -* To create a source archive and all supported packages, with a given version: +## Installation - ``` - make packages PROJECT_VERSION=3.8.1-rc.1 - ``` + * [Installation guides](https://rabbitmq.com/download.html) for various platforms + * [Kubernetes Cluster Operator](https://www.rabbitmq.com/kubernetes/operator/operator-overview.html) + * [Changelog](https://www.rabbitmq.com/changelog.html) + * [Releases](https://github.com/rabbitmq/rabbitmq-server/releases) on GitHub + * [Supported and unsupported series](https://www.rabbitmq.com/versions.html) + * [Supported Erlang versions](https://www.rabbitmq.com/which-erlang.html) -* To create all suported packages from an existing source archive: - ``` - make -C packaging SOURCE_DIST_FILE=/path/to/rabbitmq-server-3.8.1-rc.1.tar.xz - ``` +## Tutorials & Documentation -The standalone package is different because it embeds the build -platform's Erlang copy. Thus on Linux for instance, only the -`linux-x86_64` standalone package will be built. To build the OS X -standalone package, you need to run the following command on an OS X -build host: + * [RabbitMQ tutorials](https://rabbitmq.com/getstarted.html) + * [All documentation guides](https://rabbitmq.com/documentation.html) + * [CLI tools guide](https://rabbitmq.com/cli.html) + * [Configuration guide](https://rabbitmq.com/configure.html) + * [Client libraries and tools](https://rabbitmq.com/devtools.html) + * [Monitoring guide](https://rabbitmq.com/monitoring.html) + * [Production checklist](https://rabbitmq.com/production-checklist.html) + * [Runnable tutorials](https://github.com/rabbitmq/rabbitmq-tutorials/) + * [Documentation source](https://github.com/rabbitmq/rabbitmq-website/) -``` -make package-standalone-macosx -# or -make -C packaging package-standalone-macosx SOURCE_DIST_FILE=/path/to/rabbitmq-server-3.8.1-rc.1.tar.xz -``` -The instructions in the [`PKG_LINUX.md`](PKG_LINUX.md) document include a -script to install the necessary pre-requisites for building package archives as -well as `deb` and `rpm` packages. +## Getting Help -## Source archive + * [RabbitMQ mailing list](https://groups.google.com/forum/#!forum/rabbitmq-users) + * [Commercial support](https://rabbitmq.com/services.html) from [Pivotal](https://pivotal.io) for open source RabbitMQ + * [Community Slack](https://rabbitmq-slack.herokuapp.com/) + * `#rabbitmq` on Freenode -### How to create it -The source archive is created with the following command: -``` -make source-dist -``` +## Contributing -It uses Erlang.mk's `PROJECT_VERSION` variable to set the version of the -source archive. If the variable is unset, Erlang.mk computes a value -based on the last tag and the current HEAD. +See [CONTRIBUTING.md](./CONTRIBUTING.md) and our [development process overview](https://rabbitmq.com/github.html). -Here is an example with an explicit version: -``` -make source-dist PROJECT_VERSION=3.8.1-rc.1 -``` +Questions about contributing, internals and so on are very welcome on the [mailing list](https://groups.google.com/forum/#!forum/rabbitmq-users). -The version is automatically propagated to the broker and plugins so -they all advertise the same version. -The result is then available in the `PACKAGES` subdirectory. You can -override the output directory with the `PACKAGES_DIR` variable: -``` -make source-dist PROJDCT_VERSION=3.8.1-rc.1 \ - PACKAGES_DIR=/tmp -``` +## Licensing -By default, two archives are produced: -* a `tar.xz` file; -* a `zip` file. +RabbitMQ server is [licensed under the MPL 2.0](LICENSE-MPL-RabbitMQ). -You can ask for more/different types by specifying the -`SOURCE_DIST_SUFFIXES` variable: -``` -make source-dist PROJECT_VERSION=3.8.1-rc.1 \ - SOURCE_DIST_SUFFIXES='tar.xz tar.gz' -``` -Supported archive types are: -* `tar.bz2`; -* `tar.gz`; -* `tar.xz`; -* `zip`. +## Building From Source and Packaging -### What is included + * [Building RabbitMQ from Source](https://rabbitmq.com/build-server.html) + * [Building RabbitMQ Distribution Packages](https://rabbitmq.com/build-server.html) -The source archive includes the broker and a set of plugins. The default -list of plugins is in the `plugins.mk` file. -You can override this list by setting the `PLUGINS` variable to the list -you want: -``` -make source-dist PROJECT_VERSION=3.8.1-rc.1 \ - PLUGINS='rabbitmq_shovel rabbitmq_rabbitmq_shovel_management' -``` +## Copyright -Dependencies are automatically included. - -## Packages - -Packages can be built with an existing source archive or create the -source archive automatically. - -If you want to use an existing archive, use `packaging/Makefile`: -``` -make -C packaging package-$type \ - SOURCE_DIST_FILE=/path/to/rabbitmq-server-$version.tar.xz \ - ... -``` - -This has the following rules: -* The archive must be a `tar.xz` file. -* It can automatically take the only archive available under `PACKAGES`. - However, if there is none or multiple archive, you must specify the - `SOURCE_DIST_FILE` variable. - -If you want the source archive to be created automatically, use the -top-level `Makefile`: -``` -make package-$type PROJECT_VERSION=3.8.1-rc.1 ... -``` - -Packages are written to `PACKAGES_DIR`, like the source archive. - -Each package type is further described separately because most of them -have versioning specificities. - -### `generic-unix` package - -To create it: -``` -make package-generic-unix -``` - -There is no package revision, only the project version and no -restriction on it. - -`packaging/generic-unix/Makefile` tries to determine the version based -on the source archive filename. If it fails, you can specify the version -with the `VERSION` variable: -``` -make -C packaging package-generic-unix \ - SOURCE_DIST_FILE=rabbitmq-server.tar.xz \ - VERSION=3.8.1-rc.1 -``` - -### Debian package - -To create it: -``` -make package-deb -``` - -The package may have a different versioning than the project and may -include an additional package revision. In particular, the package -version can't have any `-` characters. - -`packaging/debs/Debian/Makefile` tries to determine the version based -on the source archive filename. If it fails, you can specify the version -with the `VERSION` variable: -``` -make -C packaging package-deb \ - SOURCE_DIST_FILE=rabbitmq-server.tar.xz \ - VERSION=3.8.1-rc.1 -``` - -By default, the package version is converted from `VERSION` with -all `-` characters replaced by `~` (eg. `3.8.1~rc.1` in the example -above). If you want to override that conversion, you can specify the -`DEBIAN_VERSION` variable: -``` -make -C packaging package-deb \ - SOURCE_DIST_FILE=rabbitmq-server.tar.xz \ - VERSION=3.8.1-rc.1 - DEBIAN_VERSION=3.8.1~rc.1 -``` - -### RPM package - -We support RedHat and OpenSUSE RPM packages and both are created by default: - -To create them: -``` -make package-rpm -``` - -You can create a single one with: -``` -make package-rpm-fedora -make package-rpm-suse -``` - -RPM packages have the same restrictions as Debian packages and use the -same default version conversion. To override the converted version, use -the `RPM_VERSION` variable. See the "Debian package" section above for -more details. - -`packaging/RPMS/Fedora/Makefile`, which handles both RedHar and OpenSUSE -flavors, accepts the `RPM_OS` variable to set the flavor. It can be: -* `fedora`; -* `suse`. - -### Windows package - -We create two artefacts: - -* a Zip archive, resembling the `generic-unix` package; -* an installer. - -To create them: - -``` -make package-windows -``` - -To create them separately: - -``` -make -C packaging/windows # the Zip archive -make -C packaging/windows-exe # the installer -``` - -The Zip archive has no package revision, only the project version and no -restriction on it. It supports the same `VERSION` as the `generic-unix` -package. - -The installer requires a *product version* which must be 4 integers -separated by `.` characters. Furthermore, unlike other packages, this -one requires the Zip archive as its input, not the source archive. - -So you need to built the Zip archive first, then the installer. You can -specify the path to the Zip archive using the `ZIP` variable: - -``` -make -C packaging/windows-exe ZIP=/path/to/rabbitmq-server-windows.zip -``` - -By default, the *product version* is the project version where -everything following the third integer was replaced by `.0`. Thus it's -only fine if the version is a semver-based version (eg. 3.8.1-pre.3 or -3.8.2). If the version doesn't conform to that, you need to set the -`PRODUCT_VERSION` variable: - -``` -make package-windows PROJECT_VERSION=3.8.1-rc.1 PRODUCT_VERSION=3.8.1.0 -``` - -To build the Windows package using a Windows machine, follow the -instructions in [`PKG_WINDOWS.md`](PKG_WINDOWS.md). - -### Standalone package - -This is the equivalent of the `generic-unix` package with Erlang -embbeded. - -To create it: -``` -make -C packaging/standalone SOURCE_DIST_FILE=... VERSION=... -``` - -There is no package revision, only the project version and no -restriction on it. - -Unlike other packages, the top-level `Makefile` and `packaging/Makefile` -provide targets to build the standalone package for specific platforms: -``` -make package-standalone-macosx -make package-standalone-linux-x86_64 -make package-standalone-freebsd-x86_64 -``` - -Cross-build isn't supported so using those targets on incompatible -platforms is a no-op. - -If you want to build a standalone package for your platform, you can use -`packaging/standalone/Makefile` as described at the beginning of this -section. - -### Building all packages in one go - -If you want to build all packages in one command, you can use the -following helpers: -``` -# Automatically creates the source archive. -make packages - -# Use an existing archive. -make -C packaging package SOURCE_DIST_FILE=... -``` - -However, be careful with the versioning! Because all package have -incompatible requirements, you can only use a version with 3 integers -(like a final semver-based version): -``` -make packages PROJECT_VERSION=3.8.1 -make -C packaging packages SOURCE_DIST_FILE=rabbitmq-server-3.8.1.tar.xz -``` - -If you do not follow that rule, the build will fail one way or another; -probably in the Windows package because of the *product version* -restrictions. - -Another possibility is to specify the Windows *product version* and -rely on automatic conversion for Debian and RPM packages (or use the -`DEBIAN_VERSION` and `RPM_VERSION` variables), but this is untested: -``` -make packages PROJECT_VERSION=3.8.1-rc.1 PRODUCT_VERSION=3.8.1.0 -``` +(c) 2007-2020 VMware, Inc. or its affiliates. diff --git a/SERVER_RELEASES.md b/SERVER_RELEASES.md new file mode 100644 index 000000000000..41cfec6285ae --- /dev/null +++ b/SERVER_RELEASES.md @@ -0,0 +1,313 @@ +# RabbitMQ server releases + +This repository provides scripts and Makefiles we use to create RabbitMQ +server releases. It is organized in the following way: +* The top-level `Makefile` manages the source archive. +* There is a subdirectory inside `packaging` for each type of package we + support. + +## TL;DR + +* To create a source archive and all supported packages: + + ``` + make packages + ``` + +* To create a source archive and all supported packages, with a given version: + + ``` + make packages PROJECT_VERSION=3.8.1-rc.1 + ``` + +* To create all suported packages from an existing source archive: + + ``` + make -C packaging SOURCE_DIST_FILE=/path/to/rabbitmq-server-3.8.1-rc.1.tar.xz + ``` + +The standalone package is different because it embeds the build +platform's Erlang copy. Thus on Linux for instance, only the +`linux-x86_64` standalone package will be built. To build the OS X +standalone package, you need to run the following command on an OS X +build host: + +``` +make package-standalone-macosx +# or +make -C packaging package-standalone-macosx SOURCE_DIST_FILE=/path/to/rabbitmq-server-3.8.1-rc.1.tar.xz +``` + +The instructions in the [`PKG_LINUX.md`](PKG_LINUX.md) document include a +script to install the necessary pre-requisites for building package archives as +well as `deb` and `rpm` packages. + +## Source archive + +### How to create it + +The source archive is created with the following command: +``` +make source-dist +``` + +It uses Erlang.mk's `PROJECT_VERSION` variable to set the version of the +source archive. If the variable is unset, Erlang.mk computes a value +based on the last tag and the current HEAD. + +Here is an example with an explicit version: +``` +make source-dist PROJECT_VERSION=3.8.1-rc.1 +``` + +The version is automatically propagated to the broker and plugins so +they all advertise the same version. + +The result is then available in the `PACKAGES` subdirectory. You can +override the output directory with the `PACKAGES_DIR` variable: +``` +make source-dist PROJDCT_VERSION=3.8.1-rc.1 \ + PACKAGES_DIR=/tmp +``` + +By default, two archives are produced: +* a `tar.xz` file; +* a `zip` file. + +You can ask for more/different types by specifying the +`SOURCE_DIST_SUFFIXES` variable: +``` +make source-dist PROJECT_VERSION=3.8.1-rc.1 \ + SOURCE_DIST_SUFFIXES='tar.xz tar.gz' +``` + +Supported archive types are: +* `tar.bz2`; +* `tar.gz`; +* `tar.xz`; +* `zip`. + +### What is included + +The source archive includes the broker and a set of plugins. The default +list of plugins is in the `plugins.mk` file. + +You can override this list by setting the `PLUGINS` variable to the list +you want: +``` +make source-dist PROJECT_VERSION=3.8.1-rc.1 \ + PLUGINS='rabbitmq_shovel rabbitmq_rabbitmq_shovel_management' +``` + +Dependencies are automatically included. + +## Packages + +Packages can be built with an existing source archive or create the +source archive automatically. + +If you want to use an existing archive, use `packaging/Makefile`: +``` +make -C packaging package-$type \ + SOURCE_DIST_FILE=/path/to/rabbitmq-server-$version.tar.xz \ + ... +``` + +This has the following rules: +* The archive must be a `tar.xz` file. +* It can automatically take the only archive available under `PACKAGES`. + However, if there is none or multiple archive, you must specify the + `SOURCE_DIST_FILE` variable. + +If you want the source archive to be created automatically, use the +top-level `Makefile`: +``` +make package-$type PROJECT_VERSION=3.8.1-rc.1 ... +``` + +Packages are written to `PACKAGES_DIR`, like the source archive. + +Each package type is further described separately because most of them +have versioning specificities. + +### `generic-unix` package + +To create it: +``` +make package-generic-unix +``` + +There is no package revision, only the project version and no +restriction on it. + +`packaging/generic-unix/Makefile` tries to determine the version based +on the source archive filename. If it fails, you can specify the version +with the `VERSION` variable: +``` +make -C packaging package-generic-unix \ + SOURCE_DIST_FILE=rabbitmq-server.tar.xz \ + VERSION=3.8.1-rc.1 +``` + +### Debian package + +To create it: +``` +make package-deb +``` + +The package may have a different versioning than the project and may +include an additional package revision. In particular, the package +version can't have any `-` characters. + +`packaging/debs/Debian/Makefile` tries to determine the version based +on the source archive filename. If it fails, you can specify the version +with the `VERSION` variable: +``` +make -C packaging package-deb \ + SOURCE_DIST_FILE=rabbitmq-server.tar.xz \ + VERSION=3.8.1-rc.1 +``` + +By default, the package version is converted from `VERSION` with +all `-` characters replaced by `~` (eg. `3.8.1~rc.1` in the example +above). If you want to override that conversion, you can specify the +`DEBIAN_VERSION` variable: +``` +make -C packaging package-deb \ + SOURCE_DIST_FILE=rabbitmq-server.tar.xz \ + VERSION=3.8.1-rc.1 + DEBIAN_VERSION=3.8.1~rc.1 +``` + +### RPM package + +We support RedHat and OpenSUSE RPM packages and both are created by default: + +To create them: +``` +make package-rpm +``` + +You can create a single one with: +``` +make package-rpm-fedora +make package-rpm-suse +``` + +RPM packages have the same restrictions as Debian packages and use the +same default version conversion. To override the converted version, use +the `RPM_VERSION` variable. See the "Debian package" section above for +more details. + +`packaging/RPMS/Fedora/Makefile`, which handles both RedHar and OpenSUSE +flavors, accepts the `RPM_OS` variable to set the flavor. It can be: +* `fedora`; +* `suse`. + +### Windows package + +We create two artefacts: + +* a Zip archive, resembling the `generic-unix` package; +* an installer. + +To create them: + +``` +make package-windows +``` + +To create them separately: + +``` +make -C packaging/windows # the Zip archive +make -C packaging/windows-exe # the installer +``` + +The Zip archive has no package revision, only the project version and no +restriction on it. It supports the same `VERSION` as the `generic-unix` +package. + +The installer requires a *product version* which must be 4 integers +separated by `.` characters. Furthermore, unlike other packages, this +one requires the Zip archive as its input, not the source archive. + +So you need to built the Zip archive first, then the installer. You can +specify the path to the Zip archive using the `ZIP` variable: + +``` +make -C packaging/windows-exe ZIP=/path/to/rabbitmq-server-windows.zip +``` + +By default, the *product version* is the project version where +everything following the third integer was replaced by `.0`. Thus it's +only fine if the version is a semver-based version (eg. 3.8.1-pre.3 or +3.8.2). If the version doesn't conform to that, you need to set the +`PRODUCT_VERSION` variable: + +``` +make package-windows PROJECT_VERSION=3.8.1-rc.1 PRODUCT_VERSION=3.8.1.0 +``` + +To build the Windows package using a Windows machine, follow the +instructions in [`PKG_WINDOWS.md`](PKG_WINDOWS.md). + +### Standalone package + +This is the equivalent of the `generic-unix` package with Erlang +embbeded. + +To create it: +``` +make -C packaging/standalone SOURCE_DIST_FILE=... VERSION=... +``` + +There is no package revision, only the project version and no +restriction on it. + +Unlike other packages, the top-level `Makefile` and `packaging/Makefile` +provide targets to build the standalone package for specific platforms: +``` +make package-standalone-macosx +make package-standalone-linux-x86_64 +make package-standalone-freebsd-x86_64 +``` + +Cross-build isn't supported so using those targets on incompatible +platforms is a no-op. + +If you want to build a standalone package for your platform, you can use +`packaging/standalone/Makefile` as described at the beginning of this +section. + +### Building all packages in one go + +If you want to build all packages in one command, you can use the +following helpers: +``` +# Automatically creates the source archive. +make packages + +# Use an existing archive. +make -C packaging package SOURCE_DIST_FILE=... +``` + +However, be careful with the versioning! Because all package have +incompatible requirements, you can only use a version with 3 integers +(like a final semver-based version): +``` +make packages PROJECT_VERSION=3.8.1 +make -C packaging packages SOURCE_DIST_FILE=rabbitmq-server-3.8.1.tar.xz +``` + +If you do not follow that rule, the build will fail one way or another; +probably in the Windows package because of the *product version* +restrictions. + +Another possibility is to specify the Windows *product version* and +rely on automatic conversion for Debian and RPM packages (or use the +`DEBIAN_VERSION` and `RPM_VERSION` variables), but this is untested: +``` +make packages PROJECT_VERSION=3.8.1-rc.1 PRODUCT_VERSION=3.8.1.0 +```