[sdk/kdesrc-build] /: feat: support organising cloned source directories according to the 'layout' of repositories on invent.kde.org

[Johan Ouwerkerk]

Git commit 6c17bceb1f4e890fa588f0814843a8b8da955027 by Johan Ouwerkerk.
Committed on 23/12/2020 at 18:01.
Pushed by ouwerkerk into branch 'master'.

feat: support organising cloned source directories according to the 'layout' of repositories on invent.kde.org

Issues: #59

M  +35   -8    doc/index.docbook
M  +2    -1    modules/ksb/BuildContext.pm
M  +31   -3    modules/ksb/Module.pm

https://invent.kde.org/sdk/kdesrc-build/commit/6c17bceb1f4e890fa588f0814843a8b8da955027

diff --git a/doc/index.docbook b/doc/index.docbook
index 9e789c6..3c2ba4d 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -2320,15 +2320,42 @@ on also use that proxy server, if possible, by setting the
 <row id="conf-ignore-kde-structure">
 <entry>ignore-kde-structure</entry>
 <entry>Module setting overrides global</entry>
-<entry><para>This option is used to store the source and the build files directly
-in the name of the module. For example,
-<literal>source/extragear/network/telepathy/ktp-text-ui</literal>
-becomes
-<literal>source/ktp-text-ui</literal>.
-This option is disabled by default. If you want to enable this option you need to set it
-to <userinput>true</userinput>.</para>
+<entry>
+<para>This option is deprecated and will be removed (again) in a future release.</para>
 
-<para>This option was introduced with &kdesrc-build; 1.16.</para>
+<para>Please use <option><link linkend="conf-directory-layout">directory-layout</link></option>
+instead, which offers more options.</para>
+</entry>
+</row>
+
+<row id="conf-directory-layout">
+<entry>directory-layout</entry>
+<entry>Module setting overrides global</entry>
+<entry><para>This option is used to configure the layout which &kdesrc-build; should use when
+creating source and build directories.</para>
+<para>Currently, there are three possible values: <userinput>metadata</userinput>,
+<userinput>invent</userinput> and <userinput>flat</userinput></para>
+<para>The <userinput>flat</userinput> layout will group all modules directly underneath the top level
+source and build directories. For example,
+<literal>source/extragear/network/telepathy/ktp-text-ui</literal> in the <userinput>metadata</userinput>
+layout would be <literal>source/ktp-text-ui</literal> using the <userinput>flat</userinput> layout
+instead.
+</para>
+<para>The <userinput>invent</userinput> layout creates a directory hierarchy mirroring the relative
+paths of repositories on <ulink url="https://invent.kde.org/">invent.kde.org</ulink>. For example
+<literal>source/kde/applications/kate</literal> in the <userinput>metadata</userinput> layout would
+be <literal>source/utilities/kate</literal> using the <userinput>invent</userinput> layout instead.
+This layout only affects KDE projects. It is a good choice for people starting out with
+&kdesrc-build;.
+</para>
+<para>Finally, the <userinput>metadata</userinput> layout is the same as the old default
+behaviour. This layout organises KDE projects according to the project paths specified in the
+project metadata for these modules. This is a good choice if you want a directory layout which
+tracks with certain KDE processes, but note that this path is therefore not always stable. As a
+result, &kdesrc-build; may abandon an old copy of the repository and clone a new one for a project
+due to changes in the project metadata.</para>
+<para>By default the <userinput>metadata</userinput> layout will be used, to preserve backwards
+compatibility for existing users of &kdesrc-build;.</para>
 </entry>
 </row>
 
diff --git a/modules/ksb/BuildContext.pm b/modules/ksb/BuildContext.pm
index 25f25c3..c202c76 100644
--- a/modules/ksb/BuildContext.pm
+++ b/modules/ksb/BuildContext.pm
@@ -81,7 +81,8 @@ our %defaultGlobalFlags = (
     "delete-my-settings"         => 0, # Should only be set from cmdline
     "disable-agent-check"        => 0, # If true we don't check on ssh-agent
     "disable-snapshots"          => 1, # 2016-07-31 Temp. disabled until kde.org fixed to supply snapshots
-    "ignore-kde-structure"       => 0, # Whether to use kde dir structure like extragear/network
+    "ignore-kde-structure"       => 0, # Whether to use kde dir structure like extragear/network. Deprecated as of late December 2020/January 2021
+    "directory-layout"           => 'metadata', # Directory layout to use, can be 'flat', 'invent', 'metadata' (project path based hierarchy)
     "include-dependencies"       => 0, # 2019-08-31 Made negatable from cmdline (NB: false here but true in rcfile)
     "install-after-build"        => 1,
     "install-environment-driver" => 1, # Setup ~/.config/kde-env-*.sh for login scripts
diff --git a/modules/ksb/Module.pm b/modules/ksb/Module.pm
index 0998fff..bf67ae8 100644
--- a/modules/ksb/Module.pm
+++ b/modules/ksb/Module.pm
@@ -957,12 +957,40 @@ sub destDir
     my $destDir = $self->getOption('dest-dir');
 
     my $basePath = "";
-
+    my $layout = $self->getOption('directory-layout');
     if ($self->getOption('ignore-kde-structure')) {
+        # avoid spamming
+        if (!$self->getOption('#warned-deprecated-ignore-kde-structure')) {
+            warning("b[ignore-kde-structure] is deprecated, please use b[directory-layout] instead for b[$self]");
+        }
+        # no or equivalent layout configured, assume the user wants to use flat layout
+        if (!$layout || $layout eq 'flat') {
+            $layout = 'flat';
+        } else {
+            # avoid spamming
+            if (!$self->getOption('#warned-deprecated-ignore-kde-structure')) {
+                warning("Deprecated b[ignore-kde-structure] will be ignored in favour of b[directory-layout] for b[$self]");
+            }
+        }
+        # avoid spamming
+        $self->setOption('#warned-deprecated-ignore-kde-structure', 1);
+    }
+
+    if ($layout eq 'flat') {
         $basePath = $self->name();
     } else {
-        $basePath = shift // $self->getOption('#xml-full-path');
-        $basePath ||= $self->name(); # Default if not provided in repo-metadata
+        # invent layout only works for proper KDE projects, which have a kde:(.*).git pattern repository configured
+        if ($layout eq 'invent' && $self->getOption('repository') =~ m/kde:(.*)\.git/) {
+            $basePath = $1;
+        } else {
+            if (!$self->getOption('#warned-invalid-directory-layout') # avoid spamming
+                && $layout ne 'invent' && $layout ne 'metadata') {
+                warning("Invalid b[directory-layout] value: $layout. Will use b[default] instead for b[$self]");
+                $self->setOption('#warned-invalid-directory-layout', 1);
+            }
+            $basePath = shift // $self->getOption('#xml-full-path');
+            $basePath ||= $self->name(); # Default if not provided in repo-metadata
+        }
     }
 
     $destDir =~ s/(\$\{MODULE})|(\$MODULE\b)/$basePath/g;