diff --git a/docs/build_system.md b/docs/build_system.md index b42f2c3f73..e5968d2d3e 100644 --- a/docs/build_system.md +++ b/docs/build_system.md @@ -11,26 +11,31 @@ Packaging Details ### Version and Release Determination ### -The VERSION and RELEASE variables used by the build process are configured -in the Makefile, and are based on the `__version__` field contained within -the `awx/__init__.py file.` This string should always be of the format: +The `VERSION` and `RELEASE` variables used by the build process are configured +in the Makefile. The `VERSION` is taken from the `__version__` field contained +within the `awx/__init__.py file.` This string should always be of the format: - version-release + [0-9\.]+ -There should only be one "-" contained in the string. (Which can represent -a build/rev type release number). Example: +There should *not* be any "-" characters contained in the string. (Which can +represent a build/rev type release number). Example: - 1.2.2-0 + 1.2.2 + +The RELEASE value is generated by the Makefile during build time. While the +value can be supplied by setting the environment variable `RELEASE`, it is +recommended to let the `Makefile` determine the appropriate value. ### OFFICIAL vs. Non-OFFICIAL Builds ### -An "official" build is one that does not include a development timestamp -in the release field. This is controlled by setting the environment variable +An "official" build is one that does not include a development timestamp in the +release field. This is controlled by setting the environment variable `OFFICIAL=yes` prior to running the make command. -Non-official builds will replace the `RELEASE` variable with the following string: +Non-official builds will replace the `RELEASE` variable with the following +string: - -devYYYYmmDDHHMM + -0.gitYYYYmmDDHHMM Non-official builds should only be used for development purposes, and are copied into the nightly repos. Official builds will be copied out to the @@ -48,21 +53,21 @@ is handled by the function `sdist_awx()` in `setup.py`. The resulting tar.gz file will be named: - awx-${VERSION}-${RELEASE}.tar.gz + ansible-tower-${VERSION}-${RELEASE}.tar.gz ### RPM Build Process ### The first step of the RPM build process is to remove the `$RELEASE` from the tar.gz, since the spec file does not like to include the release. This is handled by the `rpmtar` Makefile target, which first unpacks the file, renames -the contained awx directory to simply be `awx-${VERSION}`, and finally re- -packages the file as `awx-${VERSION}.tar.gz`. +the contained directory to simply be `ansible-tower-${VERSION}`, and finally re- +packages the file as `ansible-tower-${VERSION}.tar.gz`. The main Makefile target for the rpm build is (unsurprisingly) `rpm`. This copies the re-formed sdist .tar.gz file into the rpm-build directory and then calls the rpmbuild command to create the RPM. -The spec file for this command is `packaging/rpm/awx.spec`. This file is currently +The spec file for this command is `packaging/rpm/ansible-tower.spec`. This file is currently maintained by hand, so any changelog entries must be added to it manually. All other aspects of the file (source, version, release, etc.) are picked up via variables that are set by the Makefile and do not need to be updated during @@ -74,16 +79,16 @@ The process to build a .deb is somewhat more involved, and I will not get too involved in the specifics of how the debian packaging works. The main files used in this packaging are (all found in `packaging/deb/`): - - awx.dirs - - awx.install + - ansible-tower.dirs + - ansible-tower.install - control - rules - {pre,post}{inst,rm} -The `awx.dirs` file contains the directories (listed as paths relative to the +The `ansible-tower.dirs` file contains the directories (listed as paths relative to the build root) that will be created during the packaging. -The `awx.install` file contains a list of files that will be installed directly +The `ansible-tower.install` file contains a list of files that will be installed directly by the build process rather than via the `make install` command or other steps. This is of the format "source destination" (where the destination is also a path relative to the build root).