Korora Package (KP)

A Korora package can be considered a high level package that often 
(but not always) manages all Korora specific modifications to 
upstream packages. Some packages are entirely new projects which 
Korora has baked itself but they are treated much the same.

The Korora packages are stored completely within git and are best 
managed with the Korora packaging utility called “kp”. The kp utility 
allows you to reproduce the entire Korora ecosystem, as well as 
contribute easier to the project through submission of patches and 
pull requests. 

In order to allow for the various use cases involved in the 
endeavour, the tool uses a number of options and flags that are 
controlled via a global config file, with the option to override 
these flags using local package options. This gives us the freedom 
as well as flexibility to set up and use the kp tool, to build 
korora from scratch.

To begin with, here's an annotated global config file (usually stored 
in the same dir as the kp tool) to specify the options needed by git 
and kp.


##### BEGIN -----------8< ---- kp.conf --- >8----------   ##########
# A heavily annotated kp.conf file for illustration purposes
# Name as 'kp.conf' and store this file in the same dir as "kp" tool.
# Who to build packages as (defaults to anonymous).
# Substitute with username to use developer account

KP_DEV_ACCOUNT=""  # if using for first time, leave blank
KP_DEV_EMAIL=""    #   ======"======DITTO======"========

# Protocol for git (can be 'git' or 'https' or 'ssh')
GIT_PROTOCOL="http" # again, first timers, use this
# https or ssh can be used, if you aready have GH experience
# but first time user doing anonymous fetches is better off with http

# URLs for git
GIT_URL_GIT="git://github.com/kororaproject"
GIT_URL_HTTP="https://github.com/kororaproject"
GIT_URL_SSH="[email protected]:kororaproject"

# location of git repo holding packages
GIT_URL=git://github.com/kororaproject
[email protected]:kororaproject

# Temporary location for building packages
TMP_DIR=/var/lib/kp

# Enable debug
#DEBUG=1


# N.B: Keep the dir containing the kp tool separate from the dir 
# containing all the korora packages. See above. Both dirs are 
# actually different locations within the "korora" dir tree.
#  /home/jackychan
#     |--- projects
#           |--- kpchan #<== here be all fedora/korora packages
#           |--- kp.git #<== and the "kp" tool, cloned from git
# keep reading below to get the idea behind the above dir structure

## working dirs
_CODE="/home/jackychan/projects/kpchan"
WORKING_DIR="${_CODE}/kp"
# ^^ these dirs contain all packages needed for building korora
#CONFIG_DIR="${_CODE}/kp/conf/"

# dir below refers to a dir containing kp tool checked out from repos
LIB_DIR="${_CODE}/kp.git/lib/"
LOG_DIR=/tmp

# Set the key to use for a release version, e.g. 18 and 19
KEY_ID[18]=30B55DCA
KEY_ID[19]=DCBE2AC3

### -----8<-------  EOF   kp.conf ------>8--------- EOF  ##########

As a first step, copy the contents above into the kp.conf file that
is present in the kp tool dir. Keep a copy of the original, if you 
wish. Initially get comfortable with the tool by typing 

    ./kp --help,   followed by 
    ./kp [command] --help 

respectively, where [command] is the list of available options that 
the tool can handle for building korora packages. 

The next step is to do some tool "housekeeping". This sets up the 
dir structure and other config files needed for the tool to pull the
upstream repos for the korora build. To do this type 

    ./kp  init  {or} ./kp --init

and you are ready to do business...


Now, get a feel for the various packages needed for kororification 
of your system by typing 

    ./kp  list  {or}  ./kp --list  

lists all the packages/kickstarts that are relevant for the process.
Initially the packages will come with a '-' next to them. This 
means, the package in question is available, but not checked out. 
As you start working with packages, the '-' will be replaced by 
other symbols. The help command will provide you with details on 
the various symbols and their meanings. (Hint: ./kp list --help) 

Once you can see the list of korora packages, you can issue a bulk 
checkout which will pull all the upstream repos to your local 
machine. For example, in the above example (from kp. conf above), 
when you issue a checkout, the individual packages checked out from 
the repositories will reside in the following directory: 
   "/home/jackychan/projects/kpchan/packages/" 
To checkout all or a specific [package], issue 

    ./kp checkout [package]   {or} ./kp --checkout [package] 
Examples:
    ./kp checkout handbrake # pulls handbrake tool from repos
    ./kp checkout jockey # drivers support from ubuntu's stable
    ./kp checkout  # get the full kaboodle

Note that the build operation fetches information from online 
repositories and therefore requires a working internet connection. 
If all this went smoothly, congratulations. The only thing left is 
to build korora on your machine.The next few steps show you how.

The first thing you do is to turn off selinux to "permissive" mode, 
from its default mode of "enforcing". A discussion on this is beyond 
the scope of this document; however you are referred to many 
excellent resources available on the internet. For example:
  http://wiki.centos.org/HowTos/SELinux 
  http://en.wikipedia.org/wiki/Security-Enhanced_Linux 

On the terminal, type 
    getenforce        # You *should* get "Enforcing" as response
    sudo setenforce 0 #  set mode to permissive  
    ./kp build [package]  {or}  ./kp --build [package] 
    # like checkout, omitting a package builds everything, and
    # specifying a package name builds only that package
    sudo setenforce 1 #  set mode to enforcing again 

Copy any errors that you may encounter, as it will assist in 
troubleshooting issues.

If you are satisfied with all the actions so far, and wish to deploy 
a korora ISO of your own, type this (as sudo) in your terminal.

    sudo ./kp release [gnome/kde] # self-explanatory

Now to briefly look at local(ised) configuration files that provide 
package-level granularity in controlling the kp tool. As always, 
here's an annotated file for the jockey proprietary driver support
tool, shown below:


---8<--- jockey.conf --->8---

KP_NAME=jockey
KP_VERSION=0.9.1

# indicate what the upstream source is wrapped in, 
# and where to get it
KP_UPSTREAM_SRC_TYPE=git,svn,rpm,tarball
KP_UPSTREAM_SRC_URL=

# GIT specific - what branch/commit should all package builds 
# be built relative to
KP_UPSTREAM_SRC_GIT_COMMIT=
KP_UPSTREAM_SRC_GIT_BRANCH=

# SVN specific - what revision number should all package builds 
# be built relative to
KP_UPSTREAM_SRC_SVN_REVISION


# RPM specific - what’s the reference upstream spec
KP_UPSTREAM_SPEC=%upstream%/spec


# if undefined uses upstream spec (if defined) otherwise errors 
# if missing
KP_BUILD_SPEC=

# the build spec will be dynamically built via the build spec 
# template. Patch, source and build numbers will be dynamically 
# updated based on the template.
KP_BUILD_SPEC_TEMPLATE=
KP_BUILD_ARCH=i686,x86_64

# defines the commit of the latest stable release from the 
# korora package tree
KP_RELEASE_GIT_COMMIT=


---8<--- end jockey.conf --->8---

File Tree

./upstream
Contains the primary source relating to the package, could be a GIT, 
SVN url or the extracted source from an RPM (ie akin to extracted 
files from rpmbuild/SOURCES)

./build
Contains the necessary files to build the release RPM. If the 
upstream is GIT it will contain the necessary patches (based on 
appropriate git diff). SVN would be similar. The package spec file 
would be dynamically updated based on the

./release
   contains built RPMs