diff options
Diffstat (limited to 'docs/maintainers')
| -rw-r--r-- | docs/maintainers/control-files.md | 92 | ||||
| -rw-r--r-- | docs/maintainers/portfile-functions.md | 17 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_acquire_msys.md | 39 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_apply_patches.md | 35 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_build_cmake.md | 34 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_build_msbuild.md | 64 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_configure_cmake.md | 54 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_copy_pdbs.md | 19 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_copy_tool_dependencies.md | 21 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_download_distfile.md | 46 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_execute_required_process.md | 33 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_extract_source_archive.md | 32 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_find_acquire_program.md | 39 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_from_bitbucket.md | 53 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_from_github.md | 54 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_install_cmake.md | 25 |
16 files changed, 657 insertions, 0 deletions
diff --git a/docs/maintainers/control-files.md b/docs/maintainers/control-files.md new file mode 100644 index 000000000..eb03f1d94 --- /dev/null +++ b/docs/maintainers/control-files.md @@ -0,0 +1,92 @@ +# CONTROL files + +Each port has some static metadata in the form of a `CONTROL` file. This file uses the same syntax and a subset of the fields from [the Debian `control` format][debian]. + +Field names are case-sensitive. + +[debian]: https://www.debian.org/doc/debian-policy/ch-controlfields.html + +## Source Paragraph + +The first paragraph appearing in a `CONTROL` file is the Source paragraph, which defines the core attributes of the package (name, version, and so on). + +### Example: +```no-highlight +Source: vtk +Version: 8.1.0-1 +Description: Software system for 3D computer graphics, image processing, and visualization +Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype +``` + +### Recognized fields + +#### Source +The name of the port. + +#### Version +The port version. + +This field should be an alphanumeric string which may also contain `.`, `_`, or `-`. No attempt at ordering versions is made; all versions are treated as bitstrings and are only evaluated for equality. + +By convention, if a portfile is modified without incrementing the "upstream" version, a `-#` is appended to create a unique version string. + +Example: +```no-highlight +Version: 1.0.5-2 +``` + +#### Description +A description of the library + +The first sentence of the description should concisely describe the purpose and contents of the library. Then, a larger description including the library's "proper name" should follow. + +#### Maintainer +Reserved for future use. + +#### Build-Depends +The list of dependencies required to build and use this library. + +Example: +```no-highlight +Build-Depends: zlib, libpng, libjpeg-turbo, tiff +``` + +Unlike dpkg, Vcpkg does not distinguish between build-only dependencies and runtime dependencies. The complete list of dependencies needed to successfully use the library should be specified. + +*For example: websocketpp is a header only library, and thus does not require any dependencies at install time. However, downstream users need boost and openssl to make use of the library. Therefore, websocketpp lists boost and openssl as dependencies* + +Dependencies can be filtered based on the target triplet to support different requirements on Windows Desktop versus the Universal Windows Platform. Currently, the string inside parentheses is substring-compared against the triplet name. __This will change in a future version to not depend on the triplet name.__ + +Example: +```no-highlight +Build-Depends: zlib (windows), openssl (windows), boost (windows), websocketpp (windows) +``` + +## Feature Paragraphs + +After the Source Paragraph, `CONTROL` files can list zero or more Feature Paragraphs which declare features. + +### Example: +```no-highlight +Source: vtk +Version: 8.1.0-1 +Description: Software system for 3D computer graphics, image processing, and visualization +Build-Depends: zlib, libpng, tiff, libxml2, jsoncpp, glew, freetype + +Feature: mpi +Description: MPI functionality for VTK +Build-Depends: msmpi, hdf5[parallel] +``` + +### Recognized fields + +#### Feature +The name of the feature. + +#### Description +A description of the feature + +#### Build-Depends +The list of dependencies required to build and use this feature. + +All dependencies from selected features are unioned together to produce the final dependency set for the build. This field follows the same syntax as `Build-Depends` in the Source Paragraph. diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md new file mode 100644 index 000000000..e16147f7d --- /dev/null +++ b/docs/maintainers/portfile-functions.md @@ -0,0 +1,17 @@ +<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake --> + +# Portfile helper functions
+- [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
+- [vcpkg\_apply\_patches](vcpkg_apply_patches.md)
+- [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
+- [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
+- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
+- [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)
+- [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)
+- [vcpkg\_download\_distfile](vcpkg_download_distfile.md)
+- [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)
+- [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)
+- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
+- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
+- [vcpkg\_from\_github](vcpkg_from_github.md)
+- [vcpkg\_install\_cmake](vcpkg_install_cmake.md)
diff --git a/docs/maintainers/vcpkg_acquire_msys.md b/docs/maintainers/vcpkg_acquire_msys.md new file mode 100644 index 000000000..4dc8f5391 --- /dev/null +++ b/docs/maintainers/vcpkg_acquire_msys.md @@ -0,0 +1,39 @@ +# vcpkg_acquire_msys + +Download and prepare an MSYS2 instance. + +## Usage +```cmake +vcpkg_acquire_msys(<MSYS_ROOT_VAR> [PACKAGES <package>...]) +``` + +## Parameters +### MSYS_ROOT_VAR +An out-variable that will be set to the path to MSYS2. + +### PACKAGES +A list of packages to acquire in msys. + +To ensure a package is available: `vcpkg_acquire_msys(MSYS_ROOT PACKAGES make automake1.15)` + +## Notes +A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`: +```cmake +vcpkg_acquire_msys(MSYS_ROOT) +set(BASH ${MSYS_ROOT}/usr/bin/bash.exe) + +vcpkg_execute_required_process( + COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh" + WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel + LOGNAME build-${TARGET_TRIPLET}-rel +) +``` + +## Examples + +* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) +* [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake) +* [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_acquire_msys.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_acquire_msys.cmake)
diff --git a/docs/maintainers/vcpkg_apply_patches.md b/docs/maintainers/vcpkg_apply_patches.md new file mode 100644 index 000000000..d4d8dbfec --- /dev/null +++ b/docs/maintainers/vcpkg_apply_patches.md @@ -0,0 +1,35 @@ +# vcpkg_apply_patches + +Apply a set of patches to a source tree. + +## Usage +```cmake +vcpkg_apply_patches( + SOURCE_PATH <${SOURCE_PATH}> + [QUIET] + PATCHES <patch1.patch>... +) +``` + +## Parameters +### SOURCE_PATH +The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PATCHES +A list of patches that are applied to the source tree. + +Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory. + +### QUIET +Disables the warning message upon failure. + +This should only be used for edge cases, such as patches that are known to fail even on a clean source tree. + +## Examples + +* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) +* [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake) +* [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_apply_patches.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_apply_patches.cmake)
diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md new file mode 100644 index 000000000..1e17eb975 --- /dev/null +++ b/docs/maintainers/vcpkg_build_cmake.md @@ -0,0 +1,34 @@ +# vcpkg_build_cmake + +Build a cmake project. + +## Usage: +```cmake +vcpkg_build_cmake([DISABLE_PARALLEL] [TARGET <target>]) +``` + +## Parameters: +### DISABLE_PARALLEL +The underlying buildsystem will be instructed to not parallelize + +### TARGET +The target passed to the cmake build command (`cmake --build . --target <target>`). If not specified, no target will +be passed. + +### ADD_BIN_TO_PATH +Adds the appropriate Release and Debug `bin\` directories to the path during the build such that executables can run against the in-tree DLLs. + +## Notes: +This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md). +You can use the alias [`vcpkg_install_cmake()`](vcpkg_configure_cmake.md) function if your CMake script supports the +"install" target + +## Examples: + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) +* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_build_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_cmake.cmake)
diff --git a/docs/maintainers/vcpkg_build_msbuild.md b/docs/maintainers/vcpkg_build_msbuild.md new file mode 100644 index 000000000..37f8d8df2 --- /dev/null +++ b/docs/maintainers/vcpkg_build_msbuild.md @@ -0,0 +1,64 @@ +# vcpkg_build_msbuild + +Build an msbuild-based project. + +## Usage +```cmake +vcpkg_build_msbuild( + PROJECT_PATH <${SOURCE_PATH}/port.sln> + [RELEASE_CONFIGURATION <Release>] + [DEBUG_CONFIGURATION <Debug>] + [TARGET <Build>] + [TARGET_PLATFORM_VERSION <10.0.15063.0>] + [PLATFORM <${TRIPLET_SYSTEM_ARCH}>] + [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>] + [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...] + [OPTIONS_RELEASE </p:ZLIB_LIB=X>...] + [OPTIONS_DEBUG </p:ZLIB_LIB=X>...] +) +``` + +## Parameters +### USE_VCPKG_INTEGRATION +Apply the normal `integrate install` integration for building the project. + +By default, projects built with this command will not automatically link libraries or have header paths set. + +### PROJECT_PATH +The path to the solution (`.sln`) or project (`.vcxproj`) file. + +### RELEASE_CONFIGURATION +The configuration (``/p:Configuration`` msbuild parameter) used for Release builds. + +### DEBUG_CONFIGURATION +The configuration (``/p:Configuration`` msbuild parameter) +used for Debug builds. + +### TARGET_PLATFORM_VERSION +The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter) + +### TARGET +The MSBuild target to build. (``/t:<TARGET>``) + +### PLATFORM +The platform (``/p:Platform`` msbuild parameter) used for the build. + +### PLATFORM_TOOLSET +The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build. + +### OPTIONS +Additional options passed to msbuild for all builds. + +### OPTIONS_RELEASE +Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`. + +## Examples + +* [chakracore](https://github.com/Microsoft/vcpkg/blob/master/ports/chakracore/portfile.cmake) +* [cppunit](https://github.com/Microsoft/vcpkg/blob/master/ports/cppunit/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_build_msbuild.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_msbuild.cmake)
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md new file mode 100644 index 000000000..200d358ae --- /dev/null +++ b/docs/maintainers/vcpkg_configure_cmake.md @@ -0,0 +1,54 @@ +# vcpkg_configure_cmake + +Configure CMake for Debug and Release builds of a project. + +## Usage +```cmake +vcpkg_configure_cmake( + SOURCE_PATH <${SOURCE_PATH}> + [PREFER_NINJA] + [GENERATOR <"NMake Makefiles">] + [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...] + [OPTIONS_RELEASE <-DOPTIMIZE=1>...] + [OPTIONS_DEBUG <-DDEBUGGABLE=1>...] +) +``` + +## Parameters +### SOURCE_PATH +Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`. + +### PREFER_NINJA +Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja. + +### DISABLE_PARALLEL_CONFIGURE +Disables running the CMake configure step in parallel. + +This is needed for libraries which write back into their source directory during configure. + +### GENERATOR +Specifies the precise generator to use. + +This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles". + +### OPTIONS +Additional options passed to CMake during the configuration. + +### OPTIONS_RELEASE +Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`. + +### OPTIONS_DEBUG +Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`. + +## Notes +This command supplies many common arguments to CMake. To see the full list, examine the source. + +## Examples + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) +* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_configure_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_cmake.cmake)
diff --git a/docs/maintainers/vcpkg_copy_pdbs.md b/docs/maintainers/vcpkg_copy_pdbs.md new file mode 100644 index 000000000..6bfa488db --- /dev/null +++ b/docs/maintainers/vcpkg_copy_pdbs.md @@ -0,0 +1,19 @@ +# vcpkg_copy_pdbs + +Automatically locate pdbs in the build tree and copy them adjacent to all DLLs. + +## Usage +```cmake +vcpkg_copy_pdbs() +``` + +## Notes +This command should always be called by portfiles after they have finished rearranging the binary output. + +## Examples + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_copy_pdbs.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_pdbs.cmake)
diff --git a/docs/maintainers/vcpkg_copy_tool_dependencies.md b/docs/maintainers/vcpkg_copy_tool_dependencies.md new file mode 100644 index 000000000..05d74f0b2 --- /dev/null +++ b/docs/maintainers/vcpkg_copy_tool_dependencies.md @@ -0,0 +1,21 @@ +# vcpkg_copy_tool_dependencies + +Copy all DLL dependencies of built tools into the tool folder. + +## Usage +```cmake +vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>) +``` +## Parameters +The path to the directory containing the tools. + +## Notes +This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools. + +## Examples + +* [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake) +* [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_copy_tool_dependencies.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_copy_tool_dependencies.cmake)
diff --git a/docs/maintainers/vcpkg_download_distfile.md b/docs/maintainers/vcpkg_download_distfile.md new file mode 100644 index 000000000..80ea7559a --- /dev/null +++ b/docs/maintainers/vcpkg_download_distfile.md @@ -0,0 +1,46 @@ +# vcpkg_download_distfile + +Download and cache a file needed for this port. + +This helper should always be used instead of CMake's built-in `file(DOWNLOAD)` command. + +## Usage +```cmake +vcpkg_download_distfile( + <OUT_VARIABLE> + URLS <http://mainUrl> <http://mirror1>... + FILENAME <output.zip> + SHA512 <5981de...> +) +``` +## Parameters +### OUT_VARIABLE +This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources. + +### URLS +A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given. + +### FILENAME +The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts. + +### SHA512 +The expected hash for the file. + +If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch. + +### SKIP_SHA512 +Skip SHA512 hash check for file. + +This switch is only valid when building with the `--head` command line flag. + +## Notes +The helper [`vcpkg_from_github`](vcpkg_from_github.md) should be used for downloading from GitHub projects. + +## Examples + +* [apr](https://github.com/Microsoft/vcpkg/blob/master/ports/apr/portfile.cmake) +* [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake) +* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_download_distfile.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_download_distfile.cmake)
diff --git a/docs/maintainers/vcpkg_execute_required_process.md b/docs/maintainers/vcpkg_execute_required_process.md new file mode 100644 index 000000000..4b1a7e081 --- /dev/null +++ b/docs/maintainers/vcpkg_execute_required_process.md @@ -0,0 +1,33 @@ +# vcpkg_execute_required_process + +Execute a process with logging and fail the build if the command fails. + +## Usage +```cmake +vcpkg_execute_required_process( + COMMAND <${PERL}> [<arguments>...] + WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg> + LOGNAME <build-${TARGET_TRIPLET}-dbg> +) +``` +## Parameters +### COMMAND +The command to be executed, along with its arguments. + +### WORKING_DIRECTORY +The directory to execute the command in. + +### LOGNAME +The prefix to use for the log files. + +This should be a unique name for different triplets so that the logs don't conflict when building multiple at once. + +## Examples + +* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) +* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) +* [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake) +* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_execute_required_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process.cmake)
diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md new file mode 100644 index 000000000..104032ffc --- /dev/null +++ b/docs/maintainers/vcpkg_extract_source_archive.md @@ -0,0 +1,32 @@ +# vcpkg_extract_source_archive + +Extract an archive into the source directory. + +## Usage +```cmake +vcpkg_extract_source_archive( + <${ARCHIVE}> [<${TARGET_DIRECTORY}>] +) +``` +## Parameters +### ARCHIVE +The full path to the archive to be extracted. + +This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md). + +### TARGET_DIRECTORY +If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`. + +This can be used to mimic git submodules, by extracting into a subdirectory of another archive. + +## Notes +This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive. + +## Examples + +* [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake) +* [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake) +* [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_extract_source_archive.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive.cmake)
diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md new file mode 100644 index 000000000..57a2bf75a --- /dev/null +++ b/docs/maintainers/vcpkg_find_acquire_program.md @@ -0,0 +1,39 @@ +# vcpkg_find_acquire_program + +Download or find a well-known tool. + +## Usage +```cmake +vcpkg_find_acquire_program(<VAR>) +``` +## Parameters +### VAR +This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable. + +## Notes +The current list of programs includes: + +- 7Z +- BISON +- FLEX +- GASPREPROCESSOR +- PERL +- PYTHON2 +- PYTHON3 +- JOM +- MESON +- NASM +- NINJA +- YASM +- ARIA2 (Downloader) + +Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md). + +## Examples + +* [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake) +* [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake) +* [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_find_acquire_program.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_find_acquire_program.cmake)
diff --git a/docs/maintainers/vcpkg_from_bitbucket.md b/docs/maintainers/vcpkg_from_bitbucket.md new file mode 100644 index 000000000..c8850b725 --- /dev/null +++ b/docs/maintainers/vcpkg_from_bitbucket.md @@ -0,0 +1,53 @@ +# vcpkg_from_bitbucket + +Download and extract a project from Bitbucket. +Enables support for installing HEAD `vcpkg.exe install --head <port>`. + +## Usage: +```cmake +vcpkg_from_bitbucket( + OUT_SOURCE_PATH <SOURCE_PATH> + REPO <Microsoft/cpprestsdk> + [REF <v2.0.0>] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF <master>] +) +``` + +## Parameters: +### OUT_SOURCE_PATH +Specifies the out-variable that will contain the extracted location. + +This should be set to `SOURCE_PATH` by convention. + +### REPO +The organization or user and repository on GitHub. + +### REF +A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** + +For repositories without official releases, this can be set to the full commit id of the current latest master. + +If `REF` is specified, `SHA512` must also be specified. + +### SHA512 +The SHA512 hash that should match the archive (https://bitbucket.com/${REPO}/get/${REF}.tar.gz). + +This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile. + +### HEAD_REF +The unstable git commit-ish (ideally a branch) to pull for `--head` builds. + +For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. + +## Notes: +At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. + +This exports the `VCPKG_HEAD_VERSION` variable during head builds. + +## Examples: + +* [blaze](https://github.com/Microsoft/vcpkg/blob/master/ports/blaze/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_from_bitbucket.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_bitbucket.cmake)
diff --git a/docs/maintainers/vcpkg_from_github.md b/docs/maintainers/vcpkg_from_github.md new file mode 100644 index 000000000..cf50dc445 --- /dev/null +++ b/docs/maintainers/vcpkg_from_github.md @@ -0,0 +1,54 @@ +# vcpkg_from_github + +Download and extract a project from GitHub. Enables support for `install --head`. + +## Usage: +```cmake +vcpkg_from_github( + OUT_SOURCE_PATH <SOURCE_PATH> + REPO <Microsoft/cpprestsdk> + [REF <v2.0.0>] + [SHA512 <45d0d7f8cc350...>] + [HEAD_REF <master>] +) +``` + +## Parameters: +### OUT_SOURCE_PATH +Specifies the out-variable that will contain the extracted location. + +This should be set to `SOURCE_PATH` by convention. + +### REPO +The organization or user and repository on GitHub. + +### REF +A stable git commit-ish (ideally a tag) that will not change contents. **This should not be a branch.** + +For repositories without official releases, this can be set to the full commit id of the current latest master. + +If `REF` is specified, `SHA512` must also be specified. + +### SHA512 +The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz). + +This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile. + +### HEAD_REF +The unstable git commit-ish (ideally a branch) to pull for `--head` builds. + +For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms. + +## Notes: +At least one of `REF` and `HEAD_REF` must be specified, however it is preferable for both to be present. + +This exports the `VCPKG_HEAD_VERSION` variable during head builds. + +## Examples: + +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake) +* [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_from_github.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_github.cmake)
diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md new file mode 100644 index 000000000..1b132b4f1 --- /dev/null +++ b/docs/maintainers/vcpkg_install_cmake.md @@ -0,0 +1,25 @@ +# vcpkg_install_cmake + +Build and install a cmake project. + +## Usage: +```cmake +vcpkg_install_cmake(...) +``` + +## Parameters: +See [`vcpkg_build_cmake()`](vcpkg_build_cmake.md). + +## Notes: +This command transparently forwards to [`vcpkg_build_cmake()`](vcpkg_build_cmake.md), adding a `TARGET install` +parameter. + +## Examples: + +* [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake) +* [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake) +* [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake) +* [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_install_cmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_install_cmake.cmake)
|