**WARNING**: This project is a **work in progress** (WIP)!
## What is it
## What is it
### In short
### In short
Here we turn a *software release* (SR) or a *buildout.cfg* into a *Linux package* thanks to *OBS*! It is not that simple though and you will have to read a bit on how it works before you can get your package.
Here we turn a *buildout* file or set or files (e.g. *buildout.cfg*, or *software.cfg*) into a *Debian package* thanks to *OBS*! It is not that simple though and you will have to read a bit on how it works before you can get your package.
Note: It is possible to use this project as a starting point to build packages for non Debian-like distributions, but it is not documented at the moment. You might want to read about "spec files" and use them in ```distribution-specifics/```.
You should checkout (```osc co <home-project> <package>```) in the root directory of this project. So after that, along with *Makefile* and *README.md*, you should have a directory *home-project* with a directory *package* inside.
You should checkout (```osc co <home-project> <package>```) in the root directory of this project. So after that, along with *Makefile* and *README.md*, you should have a directory ```<home-project>``` with a directory <```package>``` inside.
Don't cheat! If you don't create them with ```osc``` it won't work...
Don't cheat! If you don't create them with ```osc``` it won't work...
### 2. Adapt *build-scripts/configure_release.sh*
### 2. Adapt some files.
[TODO: describe the needed adaptations]
#### In ```build-scripts/```
### 3. Run ```make```
The scripts in ```build-scripts``` are those who run the project. Every time you use this project, you will have to modify ```build-scripts/00env.sh```:
Simply run ```make```. More explanations at section [TODO: section]
1. The software name and versions: ```$SOFTWARE_VERSION```, ```$DEBIAN_VERSION```, ```$SOFTWARE_NAME```
2. The directory where the software should be installed: ```$TARGET_DIR```
3. Your buildout file or the entry point of you buildout files: ```$BUILDOUT_ENTRY_POINT```.
Good luck!
To automatically get you buildout file(s), you can use ```git clone```, which is the default in ```build-scripts/10build_tree.sh```. If you want to use something else, please modify this script. For instance, you can copy a local directory as suggested in the comments of the script.
Some advices though: [TODO: give some tips to get the logs, etc.]
#### The compilation files
For this project to work with OBS, you will need a *Makefile* and a *buildout wrapper* in the tarball sent to OBS. They are created from templates, see ```templates/compilation-templates/``` for the templates and ```build-scripts/20compilation_templates.sh``` for the workings.
[TODO: Reorganize the rest]
If you do nothing, the templates from ```_generic``` will be used. You can create you own by adding a directory there with the same name as ```$SOFTWARE_NAME``` in ```build-scripts/00env.sh```.
### Tarballs
#### The distribution files
The *\<tarball\>* directory to be archived and sent to OBS is to be prepared in tarballs/*\<tarball\>*.
### Templates
In order to build a package, OBS uses distribution files. They are created from templates, see ```templates/distribution-templates/``` for the templates and ```build-scripts/50distrib_files.sh``` for the workings.
The *templates/* directory contains the templates used during first local run of buildout and to prepare the templates to be sent to OBS.
### Distribution specifics
At the moment, the supported distributions are only the different Debian versions, and you can only use one of them at a time. It should not take too much effort to adapt ```build-scripts/50distirb_files.sh``` for it to support more Linux distributions.
The *distribution-specifics/* directory contains the files needed to build a package in a given distribution. Currently only Debian is supported and the files are in the minimal possible stage. Do not rely solely on them for a serious build.
### Packaging with OBS
If the templates do not suit you, you can directly create a directory in ```distribution-specifics/``` with the same name as ```$SOFTWARE_NAME``` in ```build-scripts/00env.sh```. For instance, there is obviously no generic version of *post-install scripts* and if your package need some, you will have write them from scratch yourself.
Currently, only Debian is supported.
The OBS directory is prepared with obs.sh and the temporary files created for it are cleaned with clean_obs.sh. The scripts assume you already checked out your OBS project.
#### Debian
The *debian/* directory provides only the bare minimum for a package to be built. For more support you will have to add it yourself.
### Complete process
### 3. Run ```make```
#### Workflow preparation workflow
``` # block of code
make
```
or
```
./build_tree.sh
./tempate_stage.sh
./bootstrap_buildout.sh
./obs.sh
```
#### Clean workflow
Simply run ```make```.
```
make clean
```
or
```
./clean_build_tree.sh
./clean_template_stage.sh
./clean_bootstram_buildout.sh
./clean_obs.sh
```
The processing is separated in stages for more advanced uses and debugging.
------------------
In particular, you can run ```make build``` and then use the same instance of this project to work on another packaging while buildout is compiling things locally. For instance you can run several compilation in parallel by running ```make build```, wait for the buildout program to be run, and then change the name and versions in ```build-scripts/00env.sh``` and run ```make build``` again. Run ```make after_build``` to finish the process when a ```make build``` command is done.
TMP
------------------
This package aims at minimizing efforts when turning a simple set of buildout.cfg files into something OBS-compatible in order to build a package. It provides a set of scripts and some additional files to ease the process.
Note: The script are numbered in order to make it more easy for the user to follow the various steps of the processing, but there is no automation for running additionnal scripts even if they are numbered too. You can of course add scripts but you will have to add them in the ```Makefile``` yourself.
A last useful advice! The first thing done in the *Makefile target* ```after_build``` is to backup the directory in which buildout has compiled everything. The backup of ```tarballs/<SOFTWARE_AND_VERSION>``` is done in ```tarballs/backup.<SOFTWARE_AND_VERSION```.
Good luck!
The main goal is to prepare a tarball usable with the make/make install workflow. Then it is sent to OBS along with some *.spec* files. *.spec* files are used to actually package the tarball and are often specific to the distribution one wants to build a package for.
