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,31 +1,25 @@
- 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.
-   - "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:
+1) Install following packages: bc, cdbs, git, links2, pbuilder
-     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)
+2) 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 ]
+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
@@ -36,36 +30,56 @@ C) How to use the scripts
                  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:
+4) Clone TDE git repositories and extra dependency modules:
-  - cd "TDE_SRC/1_git"
+   - TDE main 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
-  - using a browser, download the source code for extra dependency modules from Slavek's PPA
+     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 and click the "Filter" button.
+     * Once the page open in your browser, select your distro in the combobox near the "Filter" button and click
-      You should get a list of 10-15 modules, depending on the distro
+       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 and show a list of .deb and other files below.
+     * 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)
+       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) Setup the build scripts locally:
+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
+   - [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
-* ./build_module.sh -sh -lr "tdebase"  -> build "tdebase" from the local sources (in TDE_SRC/2_build/build/tdebase)
+   - [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
-* ./build_module.sh -g -po "tdelibs"   -> prepare "tdelibs" for building from git sources. Source code will be available
+   - [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