build: Scan for modules in the external contrib directory ../ns-3-ext…

…ernal-contrib

CMakeLists.txt

@@ -121,6 +121,18 @@ subdirlist(libs_to_build ${CMAKE_CURRENT_SOURCE_DIR}/src)
 # Scan contribution libraries
 subdirlist(contrib_libs_to_build ${CMAKE_CURRENT_SOURCE_DIR}/contrib)
 
+# Scan for additional contribution libraries OUTSIDE the ns-3 source directory,
+# in the ns-3-external-contrib directory
+if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/../ns-3-external-contrib)
+  subdirlist(
+    external_contrib_libs_to_build
+    ${CMAKE_CURRENT_SOURCE_DIR}/../ns-3-external-contrib
+  )
+  set(contrib_libs_to_build ${contrib_libs_to_build}
+                            ${external_contrib_libs_to_build}
+  )
+endif()
+
 # Before filtering, we need to load settings from .ns3rc
 parse_ns3rc(
   ns3rc_enabled_modules ns3rc_disabled_modules ns3rc_examples_enabled

RELEASE_NOTES.md

@@ -44,6 +44,7 @@ The required Doxygen version for documentation generation is version 1.11.
 - (zigbee) Added Zigbee module support.
 - (energy) Added new information and reformatted energy module documentation.
 - (wifi) Added a new `MainPhySwitch` trace source to EmlsrManager, which is fired when the main PHY switches channel to operate on another link and provides information about the reason for starting the switch.
+- (build) Scan for contrib modules in `ns-3-external-contrib` directory, at the same level of the ns-3 directory (e.g. `./ns-3-dev/../ns-3-external-contrib/`).
 
 ### Bugs fixed
 

build-support/custom-modules/ns3-contributions.cmake

@@ -15,9 +15,15 @@ macro(process_contribution contribution_list)
   # Add contribution folders to be built
   foreach(contribname ${contribution_list})
     set(folder "contrib/${contribname}")
+    set(external_folder "../ns-3-external-contrib/${contribname}")
     if(EXISTS ${PROJECT_SOURCE_DIR}/${folder}/CMakeLists.txt)
       message(STATUS "Processing ${folder}")
       add_subdirectory(${folder})
+    elseif(EXISTS ${PROJECT_SOURCE_DIR}/${external_folder}/CMakeLists.txt)
+      message(STATUS "Processing ${external_folder}")
+      add_subdirectory(
+        ${external_folder} ${PROJECT_BINARY_DIR}/contrib/${contribname}
+      )
     else()
       message(${HIGHLIGHTED_STATUS}
               "Skipping ${folder} : it does not contain a CMakeLists.txt file"

build-support/custom-modules/ns3-executables.cmake

@@ -137,6 +137,17 @@ function(build_exec)
     )
   endif()
 
+  # Handle ns-3-external-contrib/module (which will have output binaries mapped
+  # to contrib/module)
+  if(${BEXEC_EXECUTABLE_DIRECTORY_PATH} MATCHES "ns-3-external-contrib")
+    string(
+      REGEX
+      REPLACE ".*ns-3-external-contrib" "${PROJECT_SOURCE_DIR}/build/contrib"
+              BEXEC_EXECUTABLE_DIRECTORY_PATH
+              "${BEXEC_EXECUTABLE_DIRECTORY_PATH}"
+    )
+  endif()
+
   set_runtime_outputdirectory(
     "${BEXEC_EXECNAME}" "${BEXEC_EXECUTABLE_DIRECTORY_PATH}/"
     "${BEXEC_EXECNAME_PREFIX}"

doc/manual/source/working-with-cmake.rst

@@ -415,6 +415,68 @@ Adding a module is the only case where
 
 More information on how to create a new module are provided in :ref:`Adding a New Module to ns3`.
 
+Note: Advanced users who wish to organize their custom contrib modules outside the
+`ns-3-dev/contrib` directory can take advantage of a feature introduced in ns-3.44.
+The build system now also scans for contrib modules in a dedicated ns-3-external-contrib folder.
+This approach simplifies managing a top-level project that handles multiple repositories
+without requiring explicit dependencies between them.
+
+You should have a source tree like the following:
+
+.. sourcecode:: console
+
+   $ tree -d -L 3
+   .
+   ├── ns-3-dev
+   │   ├── LICENSES
+   │   ├── bindings
+   │   │   └── python
+   │   ├── build-support
+   │   │   ├── 3rd-party
+   │   │   ├── custom-modules
+   │   │   ├── pip-wheel
+   │   │   └── test-files
+   │   ├── contrib
+   │   ├── doc
+   │   │   ├── contributing
+   │   │   ├── ...
+   │   │   └── tutorial
+   │   ├── examples
+   │   │   ├── channel-models
+   │   │   ├── ...
+   │   │   └── wireless
+   │   ├── scratch
+   │   │   ├── nested-subdir
+   │   │   ├── ...
+   │   │   └── subdir2
+   │   ├── src
+   │   │   ├── antenna
+   │   │   ├── ...
+   │   │   ├── wifi
+   │   │   └── wimax
+   │   ├── third-party
+   │   └── utils
+   │       ├── perf
+   │       └── tests
+   └── ns-3-external-contrib
+       └── nr
+           ├── LICENSES
+           ├── doc
+           ├── examples
+           ├── helper
+           ├── model
+           ├── test
+           ├── tools
+           ├── tutorial
+           └── utils
+
+The module will be automatically mapped to `ns-3-dev/contrib`, as if it was part
+of the typical contrib module location. No copying or symlink required.
+
+Note: For that to always work, you may need to adjust paths dependent on
+CMAKE_CURRENT_SOURCE_DIR, if using custom CMake constructs instead of the
+ns-3 macros.
+
 Migrating a Waf module to CMake
 *******************************
 

test.py

@@ -142,7 +142,14 @@ def parse_examples_to_run_file(
 ):
     # Look for the examples-to-run file exists.
     if not os.path.exists(examples_to_run_path):
-        return
+        # Also tests for contribs OUTSIDE the ns-3-dev directory
+        possible_external_contrib_path = examples_to_run_path.replace(
+            "contrib", f"{os.path.dirname(os.path.dirname(__file__))}/ns-3-external-contrib"
+        )
+        if os.path.exists(possible_external_contrib_path):
+            examples_to_run_path = possible_external_contrib_path
+        else:
+            return
 
     # Each tuple in the C++ list of examples to run contains
     #