Document vcpkg_make_configure/install

vcpkg/TOC.yml

@@ -357,6 +357,10 @@
       href: maintainers/functions/vcpkg_install_qmake.md
     - name: vcpkg_list
       href: maintainers/functions/vcpkg_list.md
+    - name: vcpkg_make_configure
+      href: maintainers/functions/vcpkg_make_configure.md
+    - name: vcpkg_make_install
+      href: maintainers/functions/vcpkg_make_install.md
     - name: vcpkg_minimum_required
       href: maintainers/functions/vcpkg_minimum_required.md
     - name: x_vcpkg_pkgconfig_get_modules

vcpkg/maintainers/functions/vcpkg_make_configure.md

@@ -0,0 +1,228 @@
+---
+title: vcpkg_make_configure
+description: Use vcpkg_make_configure to configure a Make-based project.
+ms.date: 01/30/2024
+---
+# vcpkg_make_configure
+
+Configure a Make-based project.
+
+## Usage
+
+```cmake
+vcpkg_make_configure(
+    SOURCE_PATH <source-path>
+    [AUTORECONF]
+    [COPY_SOURCE]
+    [DISABLE_MSVC_WRAPPERS]
+    [DISABLE_CPPFLAGS]
+    [DISABLE_DEFAULT_OPTIONS]
+    [DISABLE_MSVC_FLAG_ESCAPING]
+    [OPTIONS <configure-setting>...]
+    [OPTIONS_RELEASE <configure-setting>...]
+    [OPTIONS_DEBUG <configure-setting>...]
+    [PRE_CONFIGURE_CMAKE_COMMANDS <cmake-command>...]
+    [LANGUAGES <language>...]
+)
+```
+
+To use this function, you must depend on the helper port `vcpkg-make`:
+
+```json
+"dependencies": [
+  {
+    "name": "vcpkg-make",
+    "host": true
+  }
+]
+```
+
+## Parameters
+
+### SOURCE_PATH
+
+The directory containing the project's source files.
+
+This value is usually obtained as a result of calling a source acquisition command like [`vcpkg_from_github()`](vcpkg_from_github.md).
+
+### AUTORECONF
+
+Runs autoreconf when set.
+
+### COPY_SOURCE
+
+If specified, the source directory will be copied to the build directory before the configuration process begins. Useful for projects that modify the source tree during configuration or build.
+
+### DISABLE_MSVC_WRAPPERS
+
+By default, `vcpkg_make_configure` supplies wrappers that translate and reorder 'Unix / GCC-style' flags into 'MSVC-style' flags. This accommodates build systems that assume Unix or GCC conventions.
+
+Setting `DISABLE_MSVC_WRAPPERS` disables translation of flags, allowing tools like `cl` and `windres` to receive command-line flags without modifications.
+
+### DISABLE_MSVC_FLAG_ESCAPING
+
+By default, escape characters (e.g., -Xcompiler, -Xlinker) are added before compiler and linker flags when using MSVC. These escape characters are intended for use by the wrappers and libtool to protect flags that might contain spaces, quotes, or other special characters from being misinterpreted. Setting `DISABLE_MSVC_FLAG_ESCAPING` disables this behavior. 
+
+This can be useful in situations where you're using custom build scripts or tools that require specific flag formatting.
+
+>[!NOTE]
+>If you disable the MSVC wrappers using `DISABLE_MSVC_WRAPPERS`, this option (`DISABLE_MSVC_FLAG_ESCAPING`) has no effect because the escape characters are not added in the first place.
+
+### DISABLE_CPPFLAGS
+
+Disables the extraction of C preprocessor flags (`-D` and `-isystem`) from `CFLAGS` and `CXXFLAGS` into `CPPFLAGS`.
+
+By default, `vcpkg_make_configure` extracts preprocessor relevant flags from the `CFLAGS` and `CXXFLAGS` environment variables into `CPPFLAGS`, because preprocessor flags in vcpkg are normally supplied through compiler settings variables like `VCPKG_C_FLAGS` or `VCPKG_CXX_FLAGS`.
+
+Setting `DISABLE_CPPFLAGS` disables that behavior, leaving preprocessor relevant flags in `CFLAGS` and `CXXFLAGS`.
+
+This can be useful for projects that do not use standard environment variables or have specific preprocessor requirements.
+
+### DISABLE_DEFAULT_OPTIONS
+
+Setting this flag disables the following default configure options provided by `vcpkg_make_configure`. Use this flag only if you need complete control over the configure command line and want to specify all options manually.
+
+General Defaults:
+* --disable-silent-rules - Makes the build process output more verbose.
+* --verbose - Enables verbose output from the configure script.
+
+Library Linkage:
+* For dynamic library builds: --enable-shared and --disable-static
+* For static library builds: --disable-shared and --enable-static
+
+Installation Directories:
+* Adjusts standard directories (bin, lib, share, etc.) to conform with vcpkg's layout.
+* Always Set:
+  - `--prefix` : The base installation directory, adjusted per build type (release or debug).
+  - `--bindir` : Subdirectory under the prefix for executable programs
+  - `--sbindir`: Subdirectory under the prefix for system administration programs
+  - `--libdir` : Subdirectory under the prefix for libraries (shared or static)
+  - `--mandir` : Subdirectory under the prefix for manual pages (man files)
+  - `--docdir` : Subdirectory under the prefix for documentation
+  - `--datarootdir` : Subdirectory under the prefix for architecture-independent data
+
+* Debug builds only:
+  - `--includedir` : Subdirectory under the prefix for header files
+
+Example Paths:
+* Release Configuration:
+  - `--prefix=${current_installed_dir}`
+  - `--bindir=${prefix}/tools/${PORT}/bin`
+  - `--sbindir=${prefix}/tools/${PORT}/sbin`
+  - `--libdir=${prefix}/lib`
+  - `--mandir=${prefix}/share/${PORT}`
+  - `--docdir=${prefix}/share/${PORT}`
+  - `--datarootdir=${prefix}/share/${PORT}`
+
+* Debug Configuration:
+  - `--prefix=${current_installed_dir}${path_suffix_DEBUG}`
+  - `--bindir=${prefix}/../tools/${PORT}${path_suffix_DEBUG}/bin`
+  - `--sbindir=${prefix}/../tools/${PORT}${path_suffix_DEBUG}/sbin`
+  - `--libdir=${prefix}/lib`
+  - `--includedir=${prefix}/../include`
+  - `--mandir=${prefix}/share/${PORT}`
+  - `--docdir=${prefix}/share/${PORT}`
+  - `--datarootdir=${prefix}/share/${PORT}`
+
+Platform-Specific Tweaks:
+* On Windows
+  - Sets `gl_cv_double_slash_root=yes` to signal to the configure script that it is running on Windows, where paths can begin with double slashes (//).
+  - Sets `ac_cv_func_memmove=yes` and `ac_cv_func_memset=yes` to indicate that the `memmove` and `memset` functions are available.
+  - sets `gl_cv_host_cpu_c_abi=no` on ARM64 builds to indicate that the compiler does not use the standard C ABI for floating-point numbers.
+
+* On Unix-like systems:
+  - Adjusts paths to match the typical Unix filesystem hierarchy (e.g., using /usr/local).
+
+>[!NOTE]
+> These default options streamline the configuration process for most projects. If you need a highly customized build, you can set `DISABLE_DEFAULT_OPTIONS` and manually provide all the necessary configuration options.
+
+### OPTIONS
+
+Additional options to pass to the configure script. Use these to specify any custom flags or settings required by the project.
+
+### OPTIONS_RELEASE
+
+Additional options to pass to the configure script. Use these to specify any custom flags or settings required by the project.
+
+These are in addition to `OPTIONS`.
+
+### OPTIONS_DEBUG
+
+Additional options to pass to the configure script. Use these to specify any custom flags or settings required by the project.
+
+These are in addition to `OPTIONS`.
+
+### PRE_CONFIGURE_CMAKE_COMMANDS
+
+Specifies a list of CMake commands to execute before the configure process for each build type. That is, if `VCPKG_BUILD_TYPE` is empty (the default), these commands will run once for debug and once for release. If `VCPKG_BUILD_TYPE` is `release`, these commands will only be once for release. This can be used to set up the environment or prepare the build in a way that the configure script requires.
+
+>[!NOTE]
+> When the `COPY_SOURCE` option is not set, the CMake commands in `PRE_CONFIGURE_CMAKE_COMMANDS` will operate directly on the files in the original source directory.
+
+Example
+
+```cmake
+function(my_preconfigure_command SRC BUILD_TYPE)
+    # Each source directory gets different version.txt files
+    if(BUILD_TYPE STREQUAL "release")
+        file(WRITE "${SRC}/version.txt" "This is a release version!")
+    else()
+        file(WRITE "${SRC}/version.txt" "This is a debug version!")
+    endif()
+    # The environment variable has different values for each configuration
+    set(ENV{SPECIAL} "${BUILD_TYPE} is magic")
+endfunction()
+
+vcpkg_make_configure(
+    # ...
+    PRE_CONFIGURE_CMAKE_COMMANDS my_preconfigure_command
+)
+```
+
+In this example, `my_preconfigure_command` will be executed twice (for "Debug" and "Release" if `VCPKG_BUILD_TYPE` is not set):
+
+Debug build: It will create `version.txt` with the content "This is a debug version!" and set the environment variable `SPECIAL` to "Debug is magic."
+Release build: It will create `version.txt` with the content "This is a release version!" and set the environment variable `SPECIAL` to "Release is magic."
+
+### LANGUAGES
+
+The `LANGUAGES` argument specifies the programming languages to be considered during the configuration and build process.
+
+Valid values are `C`, `CXX`, `ASM`, `CUDA`, `Fortran`, `HIP`, `ISPC`, `Swift`, `OBJC`, `OBJCXX`.
+
+Appends the specified languages to `VCPKG_CMAKE_CONFIGURE_OPTIONS` as `-DVCPKG_LANGUAGES=<languages>`. `vcpkg_cmake_get_vars` uses the options stored in `VCPKG_CMAKE_CONFIGURE_OPTIONS`, including the `LANGUAGES` argument, to configure a dummy CMake project and extract the necessary CMake variables. The `LANGUAGES` argument affects the configuration of the dummy CMake project used in `vcpkg_cmake_get_vars`.
+The configuration extracts relevant CMake variables for the specified languages and re-exports them as `VCPKG_DETECTED_CMAKE_*`.
+
+See, 
+```cmake
+vcpkg_make_configure(
+    SOURCE_PATH "/path/to/source"
+    LANGUAGES "C" "CXX" "Fortran"
+)
+```
+
+## Examples
+
+```cmake
+vcpkg_from_github(
+    OUT_SOURCE_PATH SOURCE_PATH
+    REPO example/examplelib
+    REF v1.2.3
+    SHA512 123456...
+)
+
+vcpkg_make_configure(
+    SOURCE_PATH ${SOURCE_PATH}
+    OPTIONS
+        --disable-silent-rules
+        --enable-foo
+    OPTIONS_DEBUG
+        --enable-debug-logs
+)
+
+vcpkg_make_install()
+```
+
+## Remarks
+
+This command replaces [`vcpkg_configure_make()`](vcpkg_configure_make.md).

vcpkg/maintainers/functions/vcpkg_make_install.md

@@ -0,0 +1,79 @@
+---
+title: vcpkg_make_install
+description: Use vcpkg_make_install to build and install a Make-based project.
+ms.date: 01/31/2024
+---
+# vcpkg_make_install
+
+Build and install a Make-based project.
+
+## Usage
+
+```cmake
+vcpkg_make_install(
+    [DISABLE_PARALLEL]
+    [LOGFILE_ROOT <root-name>]
+    [MAKEFILE <makefile-name>]
+    [TARGETS <target-name>...]
+    [OPTIONS <make-option>...]
+    [OPTIONS_RELEASE <make-option>...]
+    [OPTIONS_DEBUG <make-option>...]
+)
+```
+
+To use this function, you must depend on the helper port `vcpkg-make`:
+
+```json
+"dependencies": [
+  {
+    "name": "vcpkg-make",
+    "host": true
+  }
+]
+```
+
+## Parameters
+
+### ADD_BIN_TO_PATH
+
+Adds the configure dependent `(debug/)bin` directory to the system path. This is useful if configure builds and runs executables with shared dependencies.
+
+### DISABLE_PARALLEL
+
+By default, `vcpkg_make_install` will run make with the `-j` option to enable parallel building. If your project does not support parallel builds or you encounter issues with it, set this flag to disable parallel building. This will cause `make` to be executed without the `-j` option, running build steps sequentially.
+
+### LOGFILE_ROOT
+
+Specifies the base name for log files generated by the build. Defaults to "make".
+
+### MAKEFILE
+
+Specifies the name of the makefile to use. Defaults to "Makefile".
+
+### TARGETS
+
+Specifies the targets to pass to make. Defaults to "all;install".
+
+### OPTIONS
+
+Additional options to pass to `make` during the build.
+
+### OPTIONS_RELEASE
+
+Additional options to pass to `make` during the release build.
+
+### OPTIONS_DEBUG
+
+Additional options to pass to `make` during the debug build.
+
+## Examples
+
+```cmake
+vcpkg_from_github(OUT_SOURCE_PATH source_path ...)
+vcpkg_make_configure(SOURCE_PATH "${source_path}")
+vcpkg_make_install()
+```
+
+## Remarks
+
+This command replaces [`vcpkg_install_make()`](vcpkg_install_make.md).