[vcpkg] Implement --editable (#12200)

--editable suppresses binary caching and source re-extraction for packages listed on the command line (similar to --head).

This fundamentally changes the port maintenance loop, so several example documents were updated. To avoid users having substantial changes suddenly destroyed by forgetting to pass --editable, "clean" sources have different extract locations.

The undocumented command `build` implies `--editable`.

Co-authored-by: Robert Schumacher <roschuma@microsoft.com>

1 files changed, 65 insertions, 61 deletions

diff --git a/docs/examples/patching.md b/docs/examples/patching.md
index 77b488aad..f55cdea04 100644
--- a/docs/examples/patching.md
+++ b/docs/examples/patching.md
@@ -1,32 +1,29 @@
-## Patching Example: Patching libpng to work for x86-uwp
+## Patching Example: Patching libpng to work for x64-uwp
 
 ### Initial error logs
 First, try building:
 
 ```no-highlight
-PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
--- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp
--- DOWNLOADS=D:/src/vcpkg/downloads
--- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp
--- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng
--- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/.
--- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz
--- Extracting done
--- Configuring x86-uwp-rel
--- Configuring x86-uwp-rel done
--- Configuring x86-uwp-dbg
--- Configuring x86-uwp-dbg done
--- Build x86-uwp-rel
+PS D:\src\vcpkg> vcpkg install libpng:x64-uwp --editable
+Computing installation plan...
+The following packages will be built and installed:
+    libpng[core]:x64-uwp
+Starting package 1/1: libpng:x64-uwp
+Building package libpng[core]:x64-uwp...
+-- Using cached D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Extracting source D:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Using source at D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf
+-- Configuring x64-uwp
+-- Building x64-uwp-rel
 CMake Error at scripts/cmake/execute_required_process.cmake:14 (message):
-  Command failed: C:/Program
-  Files/CMake/bin/cmake.exe;--build;.;--config;Release
+  Command failed: C:/Program Files/CMake/bin/cmake.exe;--build;.;--config;Release
 
-  Working Directory: D:/src/vcpkg/buildtrees/libpng/x86-uwp-rel
+  Working Directory: D:/src/vcpkg/buildtrees/libpng/x64-uwp-rel
 
   See logs for more information:
 
-      D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-out.log
-      D:\src\vcpkg\buildtrees\libpng\build-x86-uwp-rel-err.log
+      D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-out.log
+      D:\src\vcpkg\buildtrees\libpng\build-x64-uwp-rel-err.log
 
 Call Stack (most recent call first):
   scripts/cmake/vcpkg_build_cmake.cmake:3 (execute_required_process)
@@ -40,19 +37,19 @@ Error: build command failed
 Next, looking at the above logs (build-...-out.log and build-...-err.log).
 
 ```no-highlight
-// build-x86-uwp-rel-out.log
+// build-x64-uwp-rel-out.log
 ...
-"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
-"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) ->
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
 (ClCompile target) -> 
-  D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj]
+  D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c(775): warning C4013: 'ExitProcess' undefined; assuming extern returning int [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
 
 
-"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
-"D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj" (default target) (3) ->
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\ALL_BUILD.vcxproj" (default target) (1) ->
+"D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj" (default target) (3) ->
 (Link target) -> 
-  pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj]
-  D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x86-uwp-rel\png.vcxproj]
+  pngerror.obj : error LNK2019: unresolved external symbol _ExitProcess referenced in function _png_longjmp [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
+  D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\Release\libpng16.dll : fatal error LNK1120: 1 unresolved externals [D:\src\vcpkg\buildtrees\libpng\x64-uwp-rel\png.vcxproj]
 
     1 Warning(s)
     2 Error(s)
@@ -65,7 +62,7 @@ Time Elapsed 00:00:04.19
 Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658(v=vs.85).aspx) shows that `ExitProcess` is only available for desktop apps. Additionally, it's useful to see the surrounding context:
 
 ```c
-/* buildtrees\libpng\src\libpng-1.6.24\pngerror.c:769 */
+/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngerror.c:769 */
     /* If control reaches this point, png_longjmp() must not return. The only
     * choice is to terminate the whole process (or maybe the thread); to do
     * this the ANSI-C abort() function is used unless a different method is
@@ -77,7 +74,7 @@ Taking a look at [MSDN](https://msdn.microsoft.com/en-us/library/windows/desktop
 
 A recursive search for `PNG_ABORT` reveals the definition:
 ```no-highlight
-PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> findstr /snipl "PNG_ABORT" *
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> findstr /snipl "PNG_ABORT" *
 CHANGES:701:  Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros
 libpng-manual.txt:432:errors will result in a call to PNG_ABORT() which defaults to abort().
 libpng-manual.txt:434:You can #define PNG_ABORT() to a function that does something
@@ -100,7 +97,7 @@ pngpriv.h:463:#    define PNG_ABORT() abort()
 This already gives us some great clues, but the full definition tells the complete story.
 
 ```c
-/* buildtrees\libpng\src\libpng-1.6.24\pngpriv.h:459 */
+/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
 #ifndef PNG_ABORT
 #  ifdef _WINDOWS_
 #    define PNG_ABORT() ExitProcess(0)
@@ -116,15 +113,15 @@ This already gives us some great clues, but the full definition tells the comple
 
 We recommend using git to create the patch file, since you'll already have it installed.
 ```no-highlight
-PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git init .
-Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/libpng-1.6.24/.git/
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git init .
+Initialized empty Git repository in D:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf/.git/
 
-PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git add .
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git add .
 warning: LF will be replaced by CRLF in ANNOUNCE.
 The file will have its original line endings in your working directory.
 ...
 
-PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git commit -m "temp"
+PS D:\src\vcpkg\buildtrees\libpng\src\v1.6.37-c993153cdf> git commit -m "temp"
 [master (root-commit) 68f253f] temp
  422 files changed, 167717 insertions(+)
 ...
@@ -132,7 +129,7 @@ PS D:\src\vcpkg\buildtrees\libpng\src\libpng-1.6.24> git commit -m "temp"
 
 Now we can modify `pngpriv.h` to use `abort()` everywhere.
 ```c
-/* buildtrees\libpng\src\libpng-1.6.24\pngpriv.h:459 */
+/* buildtrees\libpng\src\v1.6.37-c993153cdf\pngpriv.h:459 */
 #ifndef PNG_ABORT
 #  define PNG_ABORT() abort()
 #endif
@@ -140,7 +137,7 @@ Now we can modify `pngpriv.h` to use `abort()` everywhere.
 
 The output of `git diff` is already in patch format, so we just need to save the patch into the `ports/libpng` directory.
 ```no-highlight
-PS buildtrees\libpng\src\libpng-1.6.24> git diff --ignore-space-at-eol | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
+PS buildtrees\libpng\src\v1.6.37-c993153cdf> git diff --ignore-space-at-eol | out-file -enc ascii ..\..\..\..\ports\libpng\use-abort-on-all-platforms.patch
 ```
 
 Finally, we need to apply the patch after extracting the source.
@@ -163,35 +160,42 @@ vcpkg_configure_cmake(
 To be completely sure this works from scratch, we need to remove the package and rebuild it:
 
 ```no-highlight
-PS D:\src\vcpkg> vcpkg remove libpng:x86-uwp
-Package libpng:x86-uwp was successfully removed
+PS D:\src\vcpkg> vcpkg remove libpng:x64-uwp
+Package libpng:x64-uwp was successfully removed
 ```
 and complete delete the building directory: D:\src\vcpkg\buildtrees\libpng
 
 Now we try a fresh, from scratch install.
 ```no-highlight
-PS D:\src\vcpkg> vcpkg install libpng:x86-uwp
--- CURRENT_INSTALLED_DIR=D:/src/vcpkg/installed/x86-uwp
--- DOWNLOADS=D:/src/vcpkg/downloads
--- CURRENT_PACKAGES_DIR=D:/src/vcpkg/packages/libpng_x86-uwp
--- CURRENT_BUILDTREES_DIR=D:/src/vcpkg/buildtrees/libpng
--- CURRENT_PORT_DIR=D:/src/vcpkg/ports/libpng/.
--- Using cached D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz
--- Extracting source D:/src/vcpkg/downloads/libpng-1.6.24.tar.xz
--- Extracting done
--- Configuring x86-uwp-rel
--- Configuring x86-uwp-rel done
--- Configuring x86-uwp-dbg
--- Configuring x86-uwp-dbg done
--- Build x86-uwp-rel
--- Build x86-uwp-rel done
--- Build x86-uwp-dbg
--- Build x86-uwp-dbg done
--- Package x86-uwp-rel
--- Package x86-uwp-rel done
--- Package x86-uwp-dbg
--- Package x86-uwp-dbg done
-Package libpng:x86-uwp is installed
+PS D:\src\vcpkg> vcpkg install libpng:x64-uwp
+Computing installation plan...
+The following packages will be built and installed:
+    libpng[core]:x64-uwp
+Starting package 1/1: libpng:x64-uwp
+Building package libpng[core]:x64-uwp...
+-- Using cached C:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Cleaning sources at C:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf.clean. Pass --editable to vcpkg to reuse sources.
+-- Extracting source C:/src/vcpkg/downloads/glennrp-libpng-v1.6.37.tar.gz
+-- Applying patch use-abort-on-all-platforms.patch
+-- Using source at C:/src/vcpkg/buildtrees/libpng/src/v1.6.37-c993153cdf.clean
+-- Configuring x64-uwp
+-- Building x64-uwp-dbg
+-- Building x64-uwp-rel
+-- Installing: C:/src/vcpkg/packages/libpng_x64-uwp/share/libpng/copyright
+-- Performing post-build validation
+-- Performing post-build validation done
+Building package libpng[core]:x64-uwp... done
+Installing package libpng[core]:x64-uwp...
+Installing package libpng[core]:x64-uwp... done
+Elapsed time for package libpng:x64-uwp: 15.31 s
+
+Total elapsed time: 15.35 s
+
+The package libpng:x64-uwp provides CMake targets:
+
+    find_package(libpng CONFIG REQUIRED)
+    target_link_libraries(main PRIVATE png)
+
 ```
 
 Finally, to fully commit and publish the changes, we need to bump the internal release number and add the patch file to source control, then make a Pull Request!
@@ -199,6 +203,6 @@ Finally, to fully commit and publish the changes, we need to bump the internal r
 ```no-highlight
 # ports\libpng\CONTROL
 Source: libpng
-Version: 1.6.24-1
+Version: 1.6.37-1
 Build-Depends: zlib
 ```