From 5f3d5bbcd5f56f238457ec4d6b5398af8243a631 Mon Sep 17 00:00:00 2001
From: lethosor <lethosor@gmail.com>
Date: Wed, 13 Apr 2022 22:53:22 -0400
Subject: [PATCH] Add new `plugins/external` subdirectory for
 external/untracked plugins

This is more convenient for some devs than the old CMakeLists.custom.txt
solution because it allows the plugins themselves (files or folders) to be
ignored, rather than needing to remember to leave them unstaged.
---
 .gitignore             |  3 ++-
 plugins/CMakeLists.txt | 38 +++++++++++++++++++++++++++++++++-----
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index d104dc89a..3867b9dbf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -71,5 +71,6 @@ tags
 # CLion
 .idea
 
-# custom plugins
+# external plugins
+/plugins/external/
 /plugins/CMakeLists.custom.txt
diff --git a/plugins/CMakeLists.txt b/plugins/CMakeLists.txt
index 0f7d24a09..22983d617 100644
--- a/plugins/CMakeLists.txt
+++ b/plugins/CMakeLists.txt
@@ -77,6 +77,9 @@ set_source_files_properties( Brushes.h PROPERTIES HEADER_FILE_ONLY TRUE )
 # Plugins
 option(BUILD_SUPPORTED "Build the supported plugins (reveal, probe, etc.)." ON)
 if(BUILD_SUPPORTED)
+    # If you are adding a plugin that you do not intend to commit to the DFHack repo,
+    # see instructions for adding "external" plugins at the end of this file.
+
     dfhack_plugin(3dveins 3dveins.cpp)
     dfhack_plugin(add-spatter add-spatter.cpp)
     # dfhack_plugin(advtools advtools.cpp)
@@ -175,6 +178,9 @@ if(BUILD_SUPPORTED)
     dfhack_plugin(workNow workNow.cpp)
     dfhack_plugin(xlsxreader xlsxreader.cpp LINK_LIBRARIES lua xlsxio_read_STATIC zip expat)
     dfhack_plugin(zone zone.cpp LINK_LIBRARIES lua)
+
+    # If you are adding a plugin that you do not intend to commit to the DFHack repo,
+    # see instructions for adding "external" plugins at the end of this file.
 endif()
 
 # this is the skeleton plugin. If you want to make your own, make a copy and then change it
@@ -183,12 +189,34 @@ if(BUILD_SKELETON)
     add_subdirectory(skeleton)
 endif()
 
-if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.custom.txt")
-    file(WRITE "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.custom.txt" "# You can add custom plugins here to avoid touching plugins/CMakeLists.txt,
-# This can be useful if you've made modifications to that file and try to
-# switch between branches that have also made modifications to it.
 
+# To add "external" plugins without committing them to the DFHack repo:
+#
+# 1. run CMake as you normally do (this is only necessary once if
+#    `external/CMakeLists.txt` does not exist yet)
+# 2. add the plugin to the `external` folder (relative to this file).
+#    - for a multi-file plugin, either clone the repository inside of the
+#      `external` folder, or add the folder there manually.
+#    - for a single-file plugin, simply add the file there.
+# 3. add an entry to `external/CMakeLists.txt`:
+#    - add_subdirectory() for multi-file plugins in a subdirectory
+#    - dfhack_plugin() for single-file plugins
+# 4. build DFHack as normal. The plugins you added will be built as well.
+
+if(NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/external/CMakeLists.txt")
+    file(WRITE "${CMAKE_CURRENT_SOURCE_DIR}/external/CMakeLists.txt"
+"# Add external plugins here - this file is ignored by git
+
+# Recommended: use add_subdirectory() for folders that you have created within
+# this folder, or dfhack_plugin() for single files that you have added here.
+
+# See the end of /plugins/CMakeLists.txt for more details.
 ")
 endif()
 
-include(CMakeLists.custom.txt)
+include("${CMAKE_CURRENT_SOURCE_DIR}/external/CMakeLists.txt")
+
+# for backwards compatibility
+if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.custom.txt")
+    include("${CMAKE_CURRENT_SOURCE_DIR}/CMakeLists.custom.txt")
+endif()