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)
-4) Create a base folder for TDE, hereafter referred to as TDE_SRC (for example $HOME/tde_src)
+                 buildscripts: contains a local copy of the build scripts, which can be modified as required
-
+   - in TDE_SRC/1_git: 
-5) Create the following folders [ see NOTE at point 0) about folder names ]
+                 edeps  : contains extra dependency modules necessary to build TDE
- 	 - in TDE_SRC: 0_logs : contains log files for repo update and global builds (more on this later)
+                 hooks  : contains build hook scripts to execute ad-hoc code before and after the building process.
-		 						 1_git  : contains the git repo clones and build hook scripts
+                          Mainly used to apply patches automatically during the building process
-								 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)
+4) Clone TDE git repositories and extra dependency modules:
-								 buildscripts: contains a local copy of the build scripts, which can be modified as required
+   - TDE main repo
-	 - in TDE_SRC/1_git: 
+     cd "TDE_SRC/1_git"
-								 edeps  : contains extra dependency modules necessary to build TDE
+     git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde
-								 hooks  : contains build hook scripts to execute ad-hoc code before and after the building process.
+     cd tde
-												  Mainly used to apply patches automatically during the building process
+     git submodule init -- scripts
-												  
+     git submodule update -- scripts
-6) Clone TDE git repositories and extra dependency modules:
+     ./scripts/switch_all_submodules_to_head_and_clean anonymous
-  - cd "TDE_SRC/1_git"
+   - TDE packaging repo 
-  - clone tde repo          : git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde
+     cd "TDE_SRC/1_git"
-  - clone tde packaging repo: git clone https://mirror.git.trinitydesktop.org/gitea/TDE/tde-packaging
+     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
+   - extra dependency packages
-    (usually more recently updated):
+     using a browser, download the source code for extra dependency modules from Slavek's PPA
-      https://quickbuild.pearsoncomputing.net/~slavek-banko/+archive/deps-r14/+packages
+     (usually more recently updated):
-    or from the official PPA:
+       https://quickbuild.pearsoncomputing.net/~slavek-banko/+archive/deps-r14/+packages
-      https://quickbuild.pearsoncomputing.net/~trinity/+archive/trinity-nightly-build-dependencies/+packages
+     or from the official PPA:
-    NOTES:
+       https://quickbuild.pearsoncomputing.net/~trinity/+archive/trinity-nightly-build-dependencies/+packages
-    * Once the page open in your browser, select your distro in the combobox and click the "Filter" button.
+     NOTES:
-      You should get a list of 10-15 modules, depending on the distro
+     * Once the page open in your browser, select your distro in the combobox near the "Filter" button and click
-    * Click on one module at a time, it will expand and show a list of .deb and other files below.
+       the button to update. You should get a list of 10-15 modules, depending on the distro.
-    * Save those files (exclude .deb files. Only .orig.tar.xz, .dsc, .debian.tar.xz are required) and store
+     * Click on one module at a time, it will expand (or open another page) and show a list of .deb and other files.
-      them to TDE_SRC/1_git/edeps/<MODULE NAME> folder (one folder per module)
+     * 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:
+
+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.
-
+    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/
 
@@ -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