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
-------------------------------
-0) * NOTE *: you can change folder names, as long as you update the "build_config.sh" file accordingly.
-
-1) Install pbuilder and configure it 
-   (see https://wiki.ubuntu.com/PbuilderHowto and https://wiki.debian.org/PbuilderTricks for a detailed tutorial)
-   - You can use the file ".pbuilderrc" from following point 2)
-
-2) Copy files from "additional files" folder to respectivily named folder.
-   - "user_home_folder" refers to the user home folder.
-   - make sure to make the files in "user home folder/.pbuilder/hooks" executable
-
-3) Create base package with the command:
-     pbuilder --create
-   If you wish to build for a different distro, use the command:
-     DIST=<target distro> pbuilder --create
-   
-4) Create a base folder for TDE, hereafter referred to as TDE_SRC (for example $HOME/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)
-								 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:
+--------------------------
+A) Environment preparation
+--------------------------
+0) Initial notes
+   - this guide has been prepared based on a clean debian testing netinstall system without any other DE.
+     It should work for other debian/ubuntu distros as well, but eventually you may run into small differences
+     here and there.
+   - you can change folder names below, as long as you update the "build_config.sh" file accordingly.
+
+1) Install following packages: bc, cdbs, git, links2, pbuilder
+
+2) Create a base folder for TDE, hereafter referred to as TDE_SRC (for example $HOME/tde_src)
+
+3) 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
+                          
+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
+   
+8) 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.
-
-8) Add your user to the sudoers group (not required if you are root):
-    sudo adduser <your user> sudo
+    Make sure to set the variable TDE_SRC to the correct path and the variables DISTRO, DISTRO_NAME and ARCHITECTURE to
+    match the distro and architecture you want to build for.
 
 
  
-------------------------------
-  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/
 
@@ -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
-------------------------------
-1) Follow the steps in section "A) Environment preparation" (only required the first time)
+-------------------------
+C) How to use the scripts
+-------------------------
+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.
-   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
+3) Update to latest git repository using
+   ./update_git_repository.sh
+   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
-* ./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"'
+   - [sudo] ./build_module.sh -g -sl "dependencies/libr"       -> build libr package. This is a good test to check
+                                                                  whether everything is working fine
+   - [sudo] ./build_module.sh -g "tdelibs"       -> build "tdelibs" from git sources in a clean chroot environment
+   - [sudo] ./build_module.sh -g -l -sl "applications/amarok"  -> build "amarok" locally from git sources and 
+                                                                  display building logs during building
+   - [sudo] ./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
+   - [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. 
-  ./03_base_03.sh -s 3 : build this set but skip the first 3 modules of the set.
+  [sudo] ./01_base_01.sh      : build this 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
-  ./build_TDE.sh -s 4 : build all TDE, but skip the first 4 sets
+  [sudo] ./build_TDE.sh      : build all TDE
+  [sudo] ./build_TDE.sh -s 4 : build all TDE, but skip the first 4 sets