DEB build scripts: major update of README file after testing on a clean

netinstall VM.

Signed-off-by: Michele Calgaro <michele.calgaro@yahoo.it>

debian/_buildscripts/local/scripts/README.txt

@@ -1,71 +1,85 @@
- Index
+-----
--------
+Index
+-----
 A) Environment preparation
 B) Notes about scripts
 C) How to use the scripts
 
 
-------------------------------
+--------------------------
-  A) Environment preparation
+A) Environment preparation
-------------------------------
+--------------------------
-0) * NOTE *: you can change folder names, as long as you update the "build_config.sh" file accordingly.
+0) Initial notes
-
+   - this guide has been prepared based on a clean debian testing netinstall system without any other DE.
-1) Install pbuilder and configure it 
+     It should work for other debian/ubuntu distros as well, but eventually you may run into small differences
-   (see https://wiki.ubuntu.com/PbuilderHowto and https://wiki.debian.org/PbuilderTricks for a detailed tutorial)
+     here and there.
-   - You can use the file ".pbuilderrc" from following point 2)
+   - you can change folder names below, as long as you update the "build_config.sh" file accordingly.
-
+
-2) Copy files from "additional files" folder to respectivily named folder.
+1) Install following packages: bc, cdbs, git, links2, pbuilder
-   - "user_home_folder" refers to the user home folder.
+
-   - make sure to make the files in "user home folder/.pbuilder/hooks" executable
+2) Create a base folder for TDE, hereafter referred to as TDE_SRC (for example $HOME/tde_src)
-
+
-3) Create base package with the command:
+3) Create the following folders [ see NOTE at point 0) about folder names ]
-     pbuilder --create
+   - in TDE_SRC: 0_logs : contains log files for repo update and global builds (more on this later)
-   If you wish to build for a different distro, use the command:
+                 1_git  : contains the git repo clones and build hook scripts
-     DIST=<target distro> pbuilder --create
+                 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)
+                 buildscripts: contains a local copy of the build scripts, which can be modified as required
+   - in TDE_SRC/1_git: 
+                 edeps  : contains extra dependency modules necessary to build TDE
+                 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
+                          
+4) Clone TDE git repositories and extra dependency modules:
+   - TDE main repo
+     cd "TDE_SRC/1_git"
+     git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde
+     cd tde
+     git submodule init -- scripts
+     git submodule update -- scripts
+     ./scripts/switch_all_submodules_to_head_and_clean anonymous
+   - TDE packaging repo 
+     cd "TDE_SRC/1_git"
+     git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde-packaging
+   - extra dependency packages
+     using a browser, download the source code for extra dependency modules from Slavek's PPA
+     (usually more recently updated):
+       https://quickbuild.pearsoncomputing.net/~slavek-banko/+archive/deps-r14/+packages
+     or from the official PPA:
+       https://quickbuild.pearsoncomputing.net/~trinity/+archive/trinity-nightly-build-dependencies/+packages
+     NOTES:
+     * Once the page open in your browser, select your distro in the combobox near the "Filter" button and click
+       the button to update. You should get a list of 10-15 modules, depending on the distro.
+     * Click on one module at a time, it will expand (or open another page) and show a list of .deb and other files.
+     * Save those files (exclude .deb files. Only .orig.tar.xz, .dsc, .debian.tar.xz are required) and store
+       them to TDE_SRC/1_git/edeps/<MODULE NAME> folder (one folder per module).
+
+5) Add your user to the sudoers group (not required if you are root)
+     su -c "adduser <username> sudo"
+   Logout and login again to make sure the setting is applied.
+
+6) Copy the files from "TDE_SRC/1_git/tde-packaging/debian/_buildscripts/local/scripts/additional files" folder
+   to the respectivily named folders.
+   - make sure the files in "/root/.pbuilder/hooks" are executable
+
+7) Create pbuilder base package with the command:
+     sudo pbuilder --create
+   If you wish to build for a different distro or architecture, use the command:
+     sudo DIST=<target distro> ARCH=<target architecture> pbuilder --create
    
-4) Create a base folder for TDE, hereafter referred to as TDE_SRC (for example $HOME/tde_src)
+8) Setup the build scripts locally:
-
-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)
-								 buildscripts: contains a local copy of the build scripts, which can be modified as required
-	 - in TDE_SRC/1_git: 
-								 edeps  : contains extra dependency modules necessary to build TDE
-								 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 and extra dependency modules:
-  - cd "TDE_SRC/1_git"
-  - clone tde repo          : git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde
-  - clone tde packaging repo: git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde-packaging
-  - using a browser, download the source code for extra dependency modules from Slavek's PPA
-    (usually more recently updated):
-      https://quickbuild.pearsoncomputing.net/~slavek-banko/+archive/deps-r14/+packages
-    or from the official PPA:
-      https://quickbuild.pearsoncomputing.net/~trinity/+archive/trinity-nightly-build-dependencies/+packages
-    NOTES:
-    * Once the page open in your browser, select your distro in the combobox and click the "Filter" button.
-      You should get a list of 10-15 modules, depending on the distro
-    * Click on one module at a time, it will expand and show a list of .deb and other files below.
-    * Save those files (exclude .deb files. Only .orig.tar.xz, .dsc, .debian.tar.xz are required) and store
-      them to TDE_SRC/1_git/edeps/<MODULE NAME> folder (one folder per module)
-
-7) Setup the build scripts locally:
   - copy build scripts from "TDE_SRC/1_git/tde-packaging/debian/_buildscripts/local/scripts" to "TDE_SRC/buildscripts"
   - cd "TDE_SRC/buildscripts"
   - cp _build_config_template.sh build_config.sh
   - edit "build_config.sh" to set your preferences and check that the various folder names match the structure on your disk.
-
+    Make sure to set the variable TDE_SRC to the correct path and the variables DISTRO, DISTRO_NAME and ARCHITECTURE to
-8) Add your user to the sudoers group (not required if you are root):
+    match the distro and architecture you want to build for.
-    sudo adduser <your user> sudo
 
 
  
-------------------------------
+----------------------
-  B) Notes about scripts
+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 and build reports in TDE_SRC/2_build/debs/<MODULE NAME>/src/
 
@@ -98,7 +112,7 @@ Scripts used to update the local clone of the git repositories.
                         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 (experimental)
-	
+  
 - _build_config_template.sh
 Template file for building configuration. Will be copied into TDE_SRC/build_config.sh upon first execution, if not already
 done when the environment was set up.
@@ -151,36 +165,40 @@ To use a hook, create an executable script (pre_build.sh and/or post_build.sh) i
 
 
 
-------------------------------
+-------------------------
-  C) How to use the scripts
+C) How to use the scripts
-------------------------------
+-------------------------
-1) Follow the steps in section "A) Environment preparation" (only required the first time)
+1) Follow the steps in section "A) Environment preparation" (only required the first time).
 2) cd "TDE_SRC/buildscripts"
-3) ./update_git_repository.sh  -> update git repository, wait until "Update completed" is printed out.
+3) Update to latest git repository using
-   Check log in TDE_SRC/0_logs/ if you wish
+   ./update_git_repository.sh
-4) Run "pbuilder update" at the beginning of the day to update the base package to the latest version. This will speed up
+   Wait until "Update completed" is printed out. Check log in TDE_SRC/0_logs/ if you wish.
+4) Run "sudo 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.
-5) build modules as per your needs.
+5) Build modules as per your needs. 
+   - If you are not root, you need to use sudo in front of each command.
 
 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
+   - [sudo] ./build_module.sh -g -sl "dependencies/libr"       -> build libr package. This is a good test to check
-* ./build_module.sh -g -l -sl "applications/amarok"  -> build "amarok" locally from git sources and 
+                                                                  whether everything is working fine
-                                                        display building logs during building
+   - [sudo] ./build_module.sh -g "tdelibs"       -> build "tdelibs" from git sources in a clean chroot environment
-* ./build_module.sh -sh -lr "tdebase"  -> build "tdebase" from the local sources (in TDE_SRC/2_build/build/tdebase)
+   - [sudo] ./build_module.sh -g -l -sl "applications/amarok"  -> build "amarok" locally from git sources and 
-                                          in a clean chroot environment and launch a shell in case of building failure.
+                                                                  display building logs during building
-                                          Append the build result (OK, FAILED) to TDE_SRC/scripts/logs/build_result.log
+   - [sudo] ./build_module.sh -sh -lr "tdebase"  -> build "tdebase" from the local sources (in TDE_SRC/2_build/build/tdebase)
-* ./build_module.sh -g -po "tdelibs"   -> prepare "tdelibs" for building from git sources. Source code will be available
+                                                    in a clean chroot environment and launch a shell in case of building failure.
-                                          in TDE_SRC/2_build/build/tdelibs. After you have made changes to the source and
+                                                    Append the build result (OK, FAILED) to TDE_SRC/scripts/logs/build_result.log
-                                          want to build the modified package, run './build_module.sh "tdelibs"'
+   - [sudo] ./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. 
+  [sudo] ./01_base_01.sh      : build this set. 
-  ./03_base_03.sh -s 3 : build this set but skip the first 3 modules of the set.
+  [sudo] ./03_base_03.sh -s 3 : build this set but skip the first 3 modules of the set.
 
 4.3) build all TDE
-  ./build_TDE.sh      : build all TDE
+  [sudo] ./build_TDE.sh      : build all TDE
-  ./build_TDE.sh -s 4 : build all TDE, but skip the first 4 sets
+  [sudo] ./build_TDE.sh -s 4 : build all TDE, but skip the first 4 sets