DEB build script: first commit, still work in progress although

functional.

Signed-off-by: Michele Calgaro <[email protected]>

1 files changed, 175 insertions, 0 deletions

diff --git a/debian/_buildscripts/local/scripts/README.txt b/debian/_buildscripts/local/scripts/README.txt
new file mode 100644
index 000000000..6f57d3abc
--- /dev/null
+++ b/debian/_buildscripts/local/scripts/README.txt
@@ -0,0 +1,175 @@
+ Index
+-------
+A) Environment preparation
+B) Notes about scripts
+C) How to use the scripts
+
+
+ A) Environment preparation
+----------------------------
+0) * NOTE *: you can change folder names, as long as you update the "build_config.sh" file accordingly after the first run.
+1) Install pbuilder and configure it (see https://wiki.ubuntu.com/PbuilderHowto for a detailed tutorial)
+   * You can use the file ".pbuilderrc" from following point 2) - it is recommended to update the mirror to use 
+     with one near you.
+   * Create the folder "/var/cache/pbuilder/repo"  
+   * Create base package with the command:
+   DIST=<your distro> pbuilder --create
+2) copy files from "additional files" folder to respective folder.
+   "user_home_folder" is the user home folder path.
+3) Create base package with the command:
+   DIST=<your distro> pbuilder --create
+4) create a base folder for TDE, hereafter referred to as TDE_SRC (for example ~/tde_src)
+5) create the following folders [ see NOTE at point 0) about folder names ]
+- in TDE_SRC: 0_logs : contains log files for repo update and global builds (more on this later)
+							1_git  : contains the git repo clones and build hook scripts
+              2_build: folder used for build preparation and for local builds
+              3_repo : local repo for package installation (to be configured in /etc/apt/sources.list)
+- in TDE_SRC/1_git: 
+== SKIP TEMPORARILY ==  
+              edeps  : contains extra dependency modules necessary to build TDE
+== SKIP END ==
+              hooks  : contains build hook scripts to execute ad-hoc code before and after the building process.
+                       Mainly used to apply patches automatically during the building process
+6) clone TDE git repositories:
+  - cd "TDE_SRC/1_git"
+  - clone tde repo          : git clone http://scm.trinitydesktop.org/scm/git/tde
+  - clone tde packaging repo: git clone http://scm.trinitydesktop.org/scm/git/tde-packaging
+== SKIP TEMPORARILY ==
+  - download dependency modules from the official PPA:
+      https://quickbuild.pearsoncomputing.net/~trinity/+archive/trinity-nightly-build-dependencies/+packages
+    or from Slavek PPA (usually more recently updated):
+      https://quickbuild.pearsoncomputing.net/~slavek-banko/+archive/deps-r14/+packages
+    Make sure you select the correct modules for your distribution and copy them to TDE_SRC/1_git/extra-dependencies/<MODULE NAME>
+    Examples: TDE_SRC/1_git/extra-dependencies/libr, TDE_SRC/1_git/extra-dependencies/imlib, ...
+== SKIP END ==
+== TEMPORARILY ONLY ==
+ >>> @Slavek: if you have a better path for download, please let me know <<<
+  - download extra dependency .deb modules from the official PPA:
+      https://quickbuild.pearsoncomputing.net/~trinity/+archive/trinity-nightly-build-dependencies/+packages
+    or from Slavek PPA (usually more recently updated):
+      https://quickbuild.pearsoncomputing.net/~slavek-banko/+archive/deps-r14/+packages
+    and save them inside the folders
+      TDE_SRC/2_build/debs/edeps/<MODULE NAME>/
+== TEMPORARILY ONLY END ==
+
+7) cd "TDE_SRC/1_git/tde-packaging/debian/_buildscripts/local/scripts/"
+   ./update_git_repository.sh  -> the very first time this will create the TDE_SRC/build_config.sh file.
+                                  Edit the file to match your preferences.
+
+
+ B) Notes about scripts
+------------------------
+1) * Notes *
+Modules are built using the build_module.sh script. After the build is completed, the installation .deb files are located in TDE_SRC/2_build/debs/<MODULE NAME>/ and the source code in TDE_SRC/2_build/debs/<MODULE NAME>/src/
+
+The source can be either the git repo or a local copy in TDE_SRC/2_build/build/<MODULE NAME>.
+A module can be built in a clean chroot environment using pbuilder (default option) or locally using dpkg-buildpackage (useful for debugging/developing).
+When using pbuilder, a hook can be used to invoke a shell when the build fails (see also "known issues").
+
+Build logs are automatically stored to files, but can also be displayed during the build process.
+The location of a module build log is TDE_SRC/2_build/debs/<MODULE NAME>/src/__build__.log
+
+When building sets of modules or the whole TDE, a global build summary is automatically stored to TDE_SRC/0_logs/build_result.log to quickly check what built and what failed. It is recommended to delete that file before starting a new TDE build (if not, build results will be appended at the end of the file).
+
+2) * Scripts description *
+- build_module.sh: build a single module
+  Usage:
+    build_module.sh [options] module_name
+  Options:
+    -g  (Git)         : build from git repo sources. If missing, build from the local copy in build folder.
+    -l  (Local)       : build the module locally. If missing, build in a clean chroot environment
+    -sl (Show Log)    : output the building logs to terminal
+    -lr (Log Result)  : log (append) build result (OK, FAILED) to TDE_SRC/0_logs/build_result.log file
+    -sh (Shell Hook)  : use a shell hook for failing builds, only valid if building using pbuilder (clean chroot environment)
+    -po (Prepare Only): only prepare the source folder but do not build the module. Useful to prepare the source code before
+                        doing local changes/development. The module can then be built from the modified local folder
+    -d  (Debug)       : enable debug symbols if possible (debian/rules file must contain "RelWithDebInfo" for this to work)
+    -ip (Internal Pbuilder): build using internal pbuilder mode 
+	
+- _build_config_template.sh
+Template file for building configuration. Will be copied into TDE_SRC/build_config.sh upon first execution
+
+- _build_common.sh
+Utility script containing common code. No need for invoking it directly.
+
+- _build_set_common.sh
+Utility script used to build sets of modules. No need for invoking it directly.
+
+- <dd>_<set_name>.sh
+A number of scripts used to build sets of modules. Each script builds an individual set.
+Modules are built from the git sources and the build result is automatically appended to 
+TDE_SRC/0_logs/build_result.log.
+  Usage:
+    <dd>_<set_name>.sh [options] set_name
+  Options:
+    -s N: if specified, skip first N modules from the set of modules
+
+The sets are logically grouped as "base system", "applications" and "others"
+== SKIP TEMPORARILY ==  
+  00_extradeps.sh                             : dependencies modules
+== SKIP END ==
+  01_base_01.sh        - 03_base_03.sh        : TDE base system
+  04_application_01.sh - 08_application_05.sh : application modules
+  09_others_01.sh      - 10_others_02.sh      : other modules that either fail to build/install or that are somehow less used
+  91_build_base.sh                            : whole TDE base system
+  92_build_applications.sh                    : all TDE applications in 04_application_01.sh - 08_application_05.sh
+  93_build_base.sh                            : all modules in 09_others_01.sh - 10_others_02.sh
+
+- build_TDE.sh
+Script used to build the whole TDE at once. Calls the dd_setname.sh set scripts in order.
+  Usage:
+    build_TDE.sh [options]
+  Options:
+    -s N: if specified, skip first N sets from the list of sets
+    
+== SKIP TEMPORARILY: not yet provided == 
+- create_repo.sh
+Creates a local repository from the .deb files currently stored in TDE_SRC/2_build/debs. This repo can be used as installation repository, just add the following lines to /etc/apt/sources.list
+  # --- LOCAL TDE REPOSITORY ---
+  deb [arch=##your arch here (ex. amd64)## trusted=yes] file:TDE_SRC(full path, ex:/home/tde_src)/3_repo/dists/testing/main/binary-##your arch here (ex. amd64)## ./
+== SKIP END ==
+  
+- update_git_repository.sh:
+Scripts used to update the local clone of the git repositories.
+  Usage:
+    update_git_repository.sh
+
+3) * Building hooks *
+Hooks are available to execute ad-hoc code before and after the build process. For example this is very useful to automatically apply patches.
+Currently there are two type of hooks: 
+- pre_build : applied just before switching the module to quilt format and build
+- post_build: applied just after the build (dpkg-buildpackage or pbuilder) has terminated 
+To use a hook, just create an executable pre_build.sh and/or post_build.sh script in the TDE_SRC/1_git/hooks/<MODULE NAME> folder. The scripts are executed in the build_module.sh environment, so have access to all the variable defined in that file. See the files in the "hook examples" folder for real usage samples.
+
+
+ C) How to use the scripts
+---------------------------
+1) Follow the steps in section "A) Environment preparation" (only required the first time)
+2) cd "TDE_SRC/1_git/tde-packaging/debian/_buildscripts/local/scripts/"
+3) ./update_git_repository.sh  -> update git repository, wait until "Update completed" is printed out.
+   Check log in TDE_SRC/0_logs/ if you wish
+4) Run "pbuilder update" at the beginning of the day to update the base package to the latest version. This will speed up
+   the process when building several modules in sequence.
+
+Examples of real usage:
+
+4.1) build a single module
+* ./build_module.sh -g "tdelibs"  -> build "tdelibs" from git sources in a clean chroot environment
+* ./build_module.sh -g -l -sl "applications/amarok"  -> build "amarok" locally from git sources and 
+                                                        display building logs during building
+* ./build_module.sh -sh -lr "tdebase"  -> build "tdebase" from the local sources (in TDE_SRC/2_build/build/tdebase)
+                                          in a clean chroot environment and launch a shell in case of building failure.
+                                          Append the build result (OK, FAILED) to TDE_SRC/scripts/logs/build_result.log
+* ./build_module.sh -g -po "tdelibs"   -> prepare "tdelibs" for building from git sources. Source code will be available
+                                          in TDE_SRC/2_build/build/tdelibs. After you have made changes to the source and
+                                          want to build the modified package, run './build_module.sh "tdelibs"'
+                                          
+4.2) build a single set
+  (optional) delete the TDE_SRC/0_logs/build_result.log file
+  ./01_base_01.sh      : build this set. 
+  ./03_base_03.sh -s 3 : build this set but skip the first 3 modules (tdeartwork, tdegames, tdetoys)
+
+4.3) build all TDE
+  ./build_TDE.sh      : build all TDE
+  ./build_TDE.sh -s 4 : build all TDE, but skip the first 4 sets
+