From 8e96485a87faf2cb03559096346264280a37e47e Mon Sep 17 00:00:00 2001 From: Philip Kuryloski Date: Fri, 13 Nov 2020 15:01:21 +0100 Subject: 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 ++++++++------------------------------------------------------ 1 file changed, 40 insertions(+), 288 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 41cfec6285..28bb2699fd 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. -- cgit v1.2.1