External-Mirrors/awx
2
0
Fork 0
mirror of https://github.com/ansible/awx.git synced 2026-03-15 07:57:29 -02:30
Code Issues Packages Projects Releases Wiki Activity

Adding more markdown formatting to make things clearer

Browse Source
This commit is contained in:
James Cammarata
2013-07-10 14:29:16 -05:00
parent 472d5825d6
commit 07b4f90a12
1 changed files with 38 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/build_system.md
View File

@@ -12,8 +12,8 @@ Packaging Details
### Version and Release Determination ### ### Version and Release Determination ###
The VERSION and RELEASE variables used by the build process are configured The VERSION and RELEASE variables used by the build process are configured
in the Makefile, and are based on the __version__ field contained within 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 `awx/__init__.py file.` This string should always be of the format:
version-release version-release
@@ -23,9 +23,9 @@ There should only be one "-" contained in the string.
An "official" build is one that does not include a development timestamp An "official" build is one that does not include a development timestamp
in the release field. This is controlled by setting the environment variable in the release field. This is controlled by setting the environment variable
OFFICIAL=yes prior to running the make command. `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 -devYYYYmmDDHHMM
@@ -41,7 +41,7 @@ can then be installed itself via pip or used later for the RPM/DEB builds.
We are currently overriding the default python sdist function, as we are We are currently overriding the default python sdist function, as we are
pre-compiling all .py files into .pyc's and removing the plain source. This pre-compiling all .py files into .pyc's and removing the plain source. This
is handled by the function sdist_awx() in setup.py. is handled by the function `sdist_awx()` in `setup.py`.
The resulting tar.gz file will be named: The resulting tar.gz file will be named:
@@ -49,17 +49,17 @@ The resulting tar.gz file will be named:
### RPM Build Process ### ### RPM Build Process ###
The first step of the RPM build process is to remove the $RELEASE from the 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 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 handled by the `rpmtar` Makefile target, which first unpacks the file, renames
the contained awx directory to simply be awx-${VERSION}, and finally re- the contained awx directory to simply be `awx-${VERSION}`, and finally re-
packages the file as awx-${VERSION}.tar.gz. packages the file as `awx-${VERSION}.tar.gz`.
The main Makefile target for the rpm build is (unsurprising) "rpm". This copies 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 re-formed sdist .tar.gz file into the rpm-build directory and then calls
the rpmbuild command to create the RPM. 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/awx.spec`. This file is currently
maintained by hand, so any changelog entries must be added to it manually. All 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 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 variables that are set by the Makefile and do not need to be updated during
@@ -69,7 +69,7 @@ packaging.
The process to build a .deb is somewhat more involved, and I will not get too 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 involved in the specifics of how the debian packaging works. The main files used
in this packaging are (all found in packaging/deb/): in this packaging are (all found in `packaging/deb/`):
- awx.dirs - awx.dirs
- awx.install - awx.install
@@ -77,21 +77,21 @@ in this packaging are (all found in packaging/deb/):
- rules - rules
- {pre,post}{inst,rm} - {pre,post}{inst,rm}
The awx.dirs file contains the directories (listed as paths relative to the The `awx.dirs` file contains the directories (listed as paths relative to the
build root) that will be created during the packaging. build root) that will be created during the packaging.
The awx.install file contains a list of files that will be installed directly The `awx.install` file contains a list of files that will be installed directly
by the build process rather than via the "make install" or other steps. This 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 is of the format "source destination" (where the destination is also a path
relative to the build root). relative to the build root).
The control file is functionally similar to the header of a spec file, and The `control` file is functionally similar to the header of a spec file, and
contains things like the package name, requirements, etc. contains things like the package name, requirements, etc.
The rules file is really a Makefile, and contains the rules for the build The `rules` file is really a Makefile, and contains the rules for the build
process. These rules are based on the type of build you're executing (binary process. These rules are based on the type of build you're executing (binary
vs. source, for instance). Since we are building a binary-only .deb package, vs. source, for instance). Since we are building a binary-only .deb package,
the only tarket we use is the "binary" target. the only tarket we use is the `binary` target.
The pre/post scripts are analogous to the %pre/%post macros in the RPM spec, The pre/post scripts are analogous to the %pre/%post macros in the RPM spec,
and are executed at the various stages of the installation/removal. For and are executed at the various stages of the installation/removal. For
@@ -99,19 +99,19 @@ Debian/Ubuntu, these scripts do quite a bit more than the corresponding RPM
stages, since RPM packaging guidelines are generally more strict about stages, since RPM packaging guidelines are generally more strict about
starting/stopping services, etc. during the RPM installation. starting/stopping services, etc. during the RPM installation.
In the main Makefile, just as with the RPM target, the target for building In the main `Makefile`, just as with the RPM target, the target for building
the .deb's is "deb". This target begins similarly to the rpm target, in that the .deb's is `deb`. This target begins similarly to the rpm target, in that
it copies the sdist file into the deb-build directory. It then unpacks that it copies the sdist file into the deb-build directory. It then unpacks that
file there and calls the dh_make helper function. This creates several new file there and calls the `dh_make` helper function. This creates several new
directories that are used by the dpkg-buildpackage command, most importantly directories that are used by the `dpkg-buildpackage` command, most importantly
the debian and DEBIAN directories (used for the source and binary builds, the `debian` and `DEBIAN` directories (used for the source and binary builds,
respectively). The generated "debian" directory is removed and replaced with respectively). The generated `debian` directory is removed and replaced with
the files that are in packaging/deb/ and the target package name is inserted the files that are in `packaging/deb/` and the target package name is inserted
into a file that will be used as a command-line argument to dpkg-buildpackage. into a file that will be used as a command-line argument to `dpkg-buildpackage`.
This is required, otherwise the build process will try and figure out the This is required, otherwise the build process will try and figure out the
name automatically (and not always successfully). name automatically (and not always successfully).
Finally dpkg-buildpackage is called to build the .deb. Finally, `dpkg-buildpackage` is called to build the .deb.
Jenkins Jenkins
----------------------------- -----------------------------
@@ -126,19 +126,14 @@ plugins installed:
- Build Authorization Token Root Plugin: - Build Authorization Token Root Plugin:
This plugin allows build and related REST build triggers be accessed even This plugin allows build and related REST build triggers be accessed even
when anonymous users cannot see Jenkins. when anonymous users cannot see Jenkins.
- Git Client Plugin: - Git Client Plugin:
The standard git client plugin. The standard git client plugin.
- Git Parameter Plug-In: - Git Parameter Plug-In:
This plugin adds the ability to choose from git repository revisions or tags This plugin adds the ability to choose from git repository revisions or tags
- GitHub API Plugin: - GitHub API Plugin:
This plugin provides GitHub API for other plugins. This plugin provides GitHub API for other plugins.
- GitHub Plugin: - GitHub Plugin:
This plugin integrates GitHub to Jenkins. This plugin integrates GitHub to Jenkins.
- Workspace Cleanup Plugin: - Workspace Cleanup Plugin:
This plugin ensures that the root of the workspace is cleaned out between This plugin ensures that the root of the workspace is cleaned out between
builds to prevent files from previous builds leaking or breaking future builds. builds to prevent files from previous builds leaking or breaking future builds.
@@ -202,7 +197,7 @@ There are currently three classes of jobs configured in Jenkins:
The automated scans work by checking for new tags in the git repository for The automated scans work by checking for new tags in the git repository for
the given project, and when a new one is found, starting the appropriate jobs. the given project, and when a new one is found, starting the appropriate jobs.
For RPMs, a job is started for each of the supported distributions while for For RPMs, a job is started for each of the supported distributions while for
DEBs only one job is started. All of these jobs are started with OFFICIAL=yes DEBs only one job is started. All of these jobs are started with `OFFICIAL=yes`
so that an official package is produced, which will be copied out to the production so that an official package is produced, which will be copied out to the production
repositories (documented below). repositories (documented below).
@@ -218,16 +213,16 @@ Manual builds can be triggered via the Jenkins GUI. Simply log in and select the
appropriate job, and then click on the "Build with Parameters" link to the left appropriate job, and then click on the "Build with Parameters" link to the left
(or select it from the drop-down that is available from the main jobs list). (or select it from the drop-down that is available from the main jobs list).
You will be presented with a form to enter parameters. The TARGET_TAG and OFFICIAL You will be presented with a form to enter parameters. The `TARGET_TAG` and `OFFICIAL`
parameters are the same for both RPM and DEB builds, the function of which is parameters are the same for both RPM and DEB builds, the function of which is
described above. For RPM builds, there is an addition parameter named TARGET_DIST, described above. For RPM builds, there is an addition parameter named `TARGET_DIST`,
which controls the mock environment for the build. which controls the mock environment for the build.
> WARNING: Take extra care when manually triggering an OFFICIAL build at this > WARNING: Take extra care when manually triggering an `OFFICIAL` build at this
> time, as the resultant package will automatically be copied to the production > time, as the resultant package will automatically be copied to the production
> server and made available for customers to download. > server and made available for customers to download.
> NOTE: As of this writing, using the combination of TARGET_TAG=HEAD and OFFICIAL=yes > NOTE: As of this writing, using the combination of `TARGET_TAG=HEAD` and `OFFICIAL=yes`
> is allowed, however this will not be the case in the future. This will either be > is allowed, however this will not be the case in the future. This will either be
> disallowed by failing the job, or the resultant package will be copied to a third > disallowed by failing the job, or the resultant package will be copied to a third
> repository to be used for user-acceptance testing (UAT). > repository to be used for user-acceptance testing (UAT).
@@ -242,9 +237,9 @@ be found at the following location:
http://50.116.42.103/awx_nightlies_RTYUIOPOIUYTYU/ http://50.116.42.103/awx_nightlies_RTYUIOPOIUYTYU/
There are two sub-folders: deb/ and rpm/. There are two sub-folders: `deb/` and `rpm/`.
The rpm/ folder itself contains sub-folders for each distribution/architecture The `rpm/` folder itself contains sub-folders for each distribution/architecture
that we support, for example: that we support, for example:
- epel-6-{i386,x86_64} - epel-6-{i386,x86_64}
@@ -252,12 +247,12 @@ that we support, for example:
- fedora-18-{i386,x86_64} - fedora-18-{i386,x86_64}
- fedora-19-{i386,x86_64} - fedora-19-{i386,x86_64}
The deb/ folder contains several subfolders, which correspond to the normal The `deb/` folder contains several subfolders, which correspond to the normal
apt repository structure. All .deb files are located under pool, while the dists/ apt repository structure. All .deb files are located under `pool/`, while the `dists/`
directory contains the distribution-specific information. directory contains the distribution-specific information.
These nightly repositories can be used by the AWX setup playbook by running the These nightly repositories can be used by the AWX setup playbook by running the
setup.sh shell script with the following option: `setup.sh` shell script with the following option:
./setup.sh -e "aw_repo_url=http://50.116.42.103/awx_nightlies_RTYUIOPOIUYTYU/..." ./setup.sh -e "aw_repo_url=http://50.116.42.103/awx_nightlies_RTYUIOPOIUYTYU/..."
@@ -266,7 +261,7 @@ setup.sh shell script with the following option:
### Official Releases ### ### Official Releases ###
As noted above, OFFICIAL builds are copied out to the production server, and can be As noted above, `OFFICIAL` builds are copied out to the production server, and can be
found at the following location: found at the following location:
http://ansibleworks.com/awx_releases_SDFOIFWOIEFJWEOFIWEF/ http://ansibleworks.com/awx_releases_SDFOIFWOIEFJWEOFIWEF/