README.md

   1 # RPMBuilder
   2
   3 This tool allows you to build RPM files in mock environment.
   4
   5 ## What is Mock?
   6
   7 Mock is a tool for building packages. It can build packages for different architectures and
   8 different Fedora or RHEL versions than the build host has. Mock creates chroots and builds packages
   9 in them. Its only task is to reliably populate a chroot and attempt to build a package in that
  10 chroot.
  11
  12 Source: https://fedoraproject.org/wiki/Mock?rd=Subprojects/Mock
  13
  14
  15 ## How does rpmbuilder work?
  16
  17 Tool reads user provided configuration and creates checkouts of Mock settings and Git hosted
  18 projects. Dependency mapping between projects is created from spec files found in every project.
  19 When a project is build the spec file is patched so that "Version:" field is set to "git describe"
  20 value. The "Release:" field is incremented based on existing rpm files.
  21
  22 The idea for this tool has been taken from openSuse Build Service (OBS). Own tool was created since
  23 configuring OBS takes a lot of work and it does not have great support for password protected Git
  24 repositories.
  25
  26
  27 ## Prerequisite
  28
  29 ### Installing mock and createrepo
  30
  31 As a requirement for the tool to work, you need to install rpm building tool "mock" and repository
  32 tool "createrepo" to your host.
  33
  34 In Redhat/Fedora:
  35 ```
  36 $ yum install mock createrepo rpmdevtools
  37 ```
  38
  39 Ubuntu:
  40 ```
  41 $ apt-get install mock createrepo
  42 ```
  43
  44 ### Assign users to mock group
  45
  46 Users of mock also need to belong to group "mock". This allows them to run mock which uses chroot.
  47
  48 Create mock group if it does not exists in your host
  49 ```
  50 $ getent group mock || groupadd mock
  51 ```
  52
  53 Add yourself to mock group
  54 ```
  55 $ usermod -a -G mock <username>
  56 ```
  57
  58
  59 ## Running script
  60
  61 Create a workspace directory which builder can use to do checkouts and compilation. This directory
  62 should have sufficient space to store your checkouts and rpm files.
  63
  64 Example:
  65 ```
  66 $ mkdir /home/<username>/rpmworkspace
  67 ```
  68
  69 ### Building project to a rpm file
  70
  71 You can build local projects as rpm files. This is useful if you are developing a project and want
  72 to create rpm files without commiting to version control system.
  73
  74 Example of building helloworld to rpm:
  75 ```
  76 $ ./makebuild.py -w /home/<username>/rpmworkspace /home/<username>/helloworld
  77 ```
  78
  79 If you want to reconfigure Mock environment (e.g. extra Yum repositories) to be available during
  80 building, create a copy of default Mock configuration and provide it with -m option.
  81
  82 Example:
  83 ```
  84 $ cp defaults/epel-7-x86_64.cfg ~/mymock.cfg
  85 $ vim ~/mymock.cfg
  86 $ ./makebuild.py -w /home/<username>/rpmworkspace -m ~/mymock.cfg /home/<username>/helloworld
  87 ```
  88
  89 Note:
  90  - RPM package version is created from "git describe". If git describe cannot be used, package
  91    version is hard coded to a.b
  92
  93 ### Access built RPM packages
  94
  95 If there are no errors during building, rpm files can be copied from build repository under your
  96 workspace directory.
  97 Example: /home/<username>/rpmworkspace/buildrepository/epel-7-x86_64/
  98
  99
 100 ## RPM file name convention
 101
 102 Rpm packages are named and versioned so that it can be found from version control system. Rpmbuilder
 103 uses command "git describe --dirty --tags" to produce a rpm package file name. If git is unable to
 104 describe the checkout a another "git describe --dirty --all --always" command is used.
 105
 106 **Example 1:** Clone with no tags
 107 File name mymodule-master.c110.gce32b26-1.el7.x86_64.rpm states that package mymodule has been made
 108 from master branch. Package was made from 110th commit and this commit has git hash ce32b26.
 109
 110 **Example 2:** Clone with tag 1.0
 111 File name mymodule-1.0-1.el7.x86_64.rpm shows that mymodule package was made from tag 1.0.
 112
 113 **Example 3:** Clone with two changes on top of tag 1.0 git clone
 114 File mymodule-1.0.c2.gad96bc2-1.el7.x86_64.rpm shows two changes have been made on top of 1.0 and
 115 also the identifying hash.
 116
 117 **Example 4:** Clone from Example 3 and local changes
 118 File mymodule-master.dirty.c112.g1.0.2.g8193b3a-1.el7.x86_64.rpm shows that the clone directory
 119 contains local modifications which make it dirty.
 120
 121
 122 ## More usage examples
 123
 124 ### Storing build products to remote server
 125
 126 If projects are built in Jenkins, there is always danger that somebody might wipe the workspace. To
 127 protect against workspace wiping you can use stashmakebuild.py script. In your build configuration
 128 file define remote server and directory.
 129
 130 When building starts script checks from your workspace that you have directories for projects and
 131 builder. If these are missing, your remote server/directory is used to pull previous build state.
 132 After each successful build your project configuration and rpm files are stored to remote server.
 133
 134 With safemakebuild.py you need to use two additional properties: --remotehost and --remotedir.
 135
 136 ### Create package with version taken from Git
 137
 138 To read package verion from Git ("git describe") set the package Version directive in spec file as
 139 "%{_version}".
 140
 141 ### Build multiple Git projects with a build configuration file
 142
 143 Create a configuration file which contains information about the projects and mock environment.
 144 Syntax for the configuration file can be copied from provided configuration-example.ini file.
 145
 146 Example:
 147 ```
 148 $ cp configuration-example.ini /home/<username>/buildconfig.ini
 149 $ vim /home/<username>/buildconfig.ini
 150 $ ./makebuild.py -w /home/<username>/rpmworkspace -b /home/<username>/buildconfig.ini
 151 ```
 152
 153 Note:
 154  - Builder keeps track of Git commit hash. Rpm building if done if project hash has changed.
 155  - If commit hash has not changed since previous build, building is skipped.
 156
 157
 158 ## Known issues
 159
 160 1. If you are not using RedHat, CentOS or Fedora building hosts you might have problems running
 161    mock. Build requirements that have been installed by rpmbuilder to mock chroot, might not be
 162 recognized by rpm tools during building. Because of this rpm building will fail complaining that
 163 necessary build requirements are missing.
 164
 165 If your components do not have build requirements to each other, then there are no problems. This
 166 problem has been seen with Debian based distributions and it is a known bug:
 167 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=794495
 168
 169 Also spectool seems to be missing from Debian based packages. Without this tool rpmbuilder is
 170 cripled to work only with local source files. As long as you do not have any spec lines such as
 171 "SourceX http://example.com/package.tgz" you are safe.
 172 See **Debian custom spectool intallation** chapter how to install spectool to your home directory.
 173
 174
 175 2. If you change git repository url this will force rebuilding of this project even if the hash of
 176    the code remains unchanged.
 177
 178 ### Debian custom spectool intallation
 179
 180 Clone spectool git somewhere in your home directory. For example to ~/gitrepos -directory:
 181 ```
 182 cd gitrepos
 183 git clone https://pagure.io/spectool.git
 184 ```
 185 Create a symbolic link to spectool where your search PATH can find it.
 186 ```
 187 ln -s ~/gitrepos/spectool/spectool ~/bin/
 188 ```