diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/faq.md | 4 | ||||
| -rw-r--r-- | docs/examples/installing-and-using-packages.md (renamed from docs/examples/using-sqlite.md) | 6 | ||||
| -rw-r--r-- | docs/examples/packaging-github-repos.md | 59 | ||||
| -rw-r--r-- | docs/examples/packaging-zipfiles.md (renamed from docs/examples/packaging-zlib.md) | 2 | ||||
| -rw-r--r-- | docs/examples/patching.md (renamed from docs/examples/patching-libpng.md) | 2 | ||||
| -rw-r--r-- | docs/index.md | 9 | ||||
| -rw-r--r-- | docs/maintainers/portfile-functions.md | 1 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_extract_source_archive.md | 2 | ||||
| -rw-r--r-- | docs/maintainers/vcpkg_extract_source_archive_ex.md | 52 | ||||
| -rw-r--r-- | docs/users/integration.md | 2 |
10 files changed, 126 insertions, 13 deletions
diff --git a/docs/about/faq.md b/docs/about/faq.md index 0178e051a..b7c9d67c8 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -10,12 +10,12 @@ Yes! See [the `export` command](../users/integration.md#export). The `vcpkg update` command lists all packages which are out-of-sync with your current portfiles. To update a package, follow the instructions in the command. ## How do I get more libraries? -The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see [Example #2](../examples/packaging-zlib.md). +The list of libraries is enumerated from the [`ports\`](https://github.com/Microsoft/vcpkg/blob/master/ports) directory. By design, you can add and remove libraries from this directory as you see fit for yourself or your company -- see our examples on packaging [zipfiles](../examples/packaging-zipfiles.md) and [GitHub repos](../examples/packaging-github-repos.md). We recommend cloning directly from [GitHub](https://github.com/microsoft/vcpkg) and using `git pull` to update the list of portfiles. Once you've updated your portfiles, `vcpkg update` will indicate any installed libraries that are now out of date. ## Can I build a private library with this tool? -Yes. Follow [our Packaging zlib Example](../examples/packaging-zlib.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code. +Yes. Follow [our packaging zlib Example](../examples/packaging-zipfiles.md) for creating a portfile using a fake URL. Then, either pre-seed the `downloads\` folder with a zip containing your private sources or replace the normal calls to `vcpkg_download_distfile` and `vcpkg_extract_source_archive` with functions that unpack your source code. ## Can I use a prebuilt private library with this tool? Yes. The `portfile.cmake` for a library is fundamentally a script that places the headers and binaries into the correct arrangement in the `${CURRENT_PACKAGES_DIR}`, so to pull in prebuilt binaries you can write a portfile which directly downloads and arranges the files. diff --git a/docs/examples/using-sqlite.md b/docs/examples/installing-and-using-packages.md index 35da141d0..50200c877 100644 --- a/docs/examples/using-sqlite.md +++ b/docs/examples/installing-and-using-packages.md @@ -1,4 +1,4 @@ -# Example: Using Sqlite +## Installing and Using Packages Example: SQLite - [Step 1: Install](#install) - [Step 2: Use](#use) @@ -10,7 +10,7 @@ <a name="install"></a> ## Step 1: Install -First, we need to know what name [Sqlite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output: +First, we need to know what name [SQLite](https://sqlite.org) goes by in the ports tree. To do that, we'll run the `search` command and inspect the output: ```no-highlight PS D:\src\vcpkg> .\vcpkg search sqlite libodb-sqlite 2.4.0 Sqlite support for the ODB ORM library @@ -82,7 +82,7 @@ Installing new libraries will make them instantly available. ``` *Note: You will need to restart Visual Studio or perform a Build to update intellisense with the changes.* -You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For Sqlite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html). +You can now simply use File -> New Project in Visual Studio 2015 or Visual Studio 2017 and the library will be automatically available. For SQLite, you can try out their [C/C++ sample](https://sqlite.org/quickstart.html). To remove the integration for your user, you can use `.\vcpkg integrate remove`. diff --git a/docs/examples/packaging-github-repos.md b/docs/examples/packaging-github-repos.md new file mode 100644 index 000000000..af2e6141a --- /dev/null +++ b/docs/examples/packaging-github-repos.md @@ -0,0 +1,59 @@ +## Packaging Github Repos Example: libogg
+### Create the CONTROL file
+The `CONTROL` file is a simple set of fields describing the package's metadata.
+
+*For libogg, we'll create the file `ports\libogg\CONTROL` with the following contents:*
+```no-highlight
+Source: libogg
+Version: 1.3.3
+Description: Ogg is a multimedia container format, and the native file and stream format for the Xiph.org multimedia codecs.
+```
+
+### Create the portfile
+`portfile.cmake` describes how to build and install the package. First we include `vcpkg_common_functions` to give us utilities for carrying this out:
+
+```no-highlight
+include(vcpkg_common_functions)
+```
+
+Now we download the project from Github with [`vcpkg_from_github`](../maintainers/vcpkg_from_github.md):
+
+```no-highlight
+vcpkg_from_github(
+ OUT_SOURCE_PATH SOURCE_PATH
+ REPO xiph/ogg
+ REF v1.3.3
+ SHA512 0bd6095d647530d4cb1f509eb5e99965a25cc3dd9b8125b93abd6b248255c890cf20710154bdec40568478eb5c4cde724abfb2eff1f3a04e63acef0fbbc9799b
+ HEAD_REF master
+)
+```
+
+The important parts to update are `REPO` for the GitHub repository path, `REF` for a stable tag/commit to use, and `SHA512` with the checksum of the downloaded zipfile (you can get this easily by setting it to `1`, trying to install the package, and copying the checksum).
+
+Finally, we configure the project with CMake, install the package, and copy over the license file:
+
+```no-highlight
+vcpkg_configure_cmake(
+ SOURCE_PATH ${SOURCE_PATH}
+ PREFER_NINJA
+)
+vcpkg_install_cmake()
+file(INSTALL ${SOURCE_PATH}/COPYING DESTINATION ${CURRENT_PACKAGES_DIR}/share/libogg RENAME copyright)
+```
+
+Check the documentation for [`vcpkg_configure_cmake`](../maintainers/vcpkg_configure_cmake.md) and [`vcpkg_install_cmake`](../maintainers/vcpkg_install_cmake.md) if your package needs additional options.
+
+Now you can run `vcpkg install libogg` to build and install the package.
+
+### Suggested example portfiles
+In the `ports\` directory are many libraries that can be used as examples, including many that are not based on CMake.
+
+- Header only libraries
+ - rapidjson
+ - range-v3
+- MSBuild-based
+ - cppunit
+ - mpg123
+- Non-CMake, custom buildsystem
+ - openssl
+ - ffmpeg
diff --git a/docs/examples/packaging-zlib.md b/docs/examples/packaging-zipfiles.md index 1d61cfee1..ed63637fd 100644 --- a/docs/examples/packaging-zlib.md +++ b/docs/examples/packaging-zipfiles.md @@ -1,4 +1,4 @@ -## Example 2: Packaging zlib +## Packaging Zipfiles Example: zlib ### Bootstrap with `create` First, locate a globally accessible archive of the library's sources. Zip, gzip, and bzip are all supported. Strongly prefer official sources or mirrors over unofficial mirrors. diff --git a/docs/examples/patching-libpng.md b/docs/examples/patching.md index 2337b73da..98115400e 100644 --- a/docs/examples/patching-libpng.md +++ b/docs/examples/patching.md @@ -1,4 +1,4 @@ -## Example 3: Patching libpng to work for x86-uwp +## Patching Example: Patching libpng to work for x86-uwp ### Initial error logs First, try building: diff --git a/docs/index.md b/docs/index.md index 90245d36a..69dbdcd1e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,13 +2,14 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving; your involvement are vital to its success! -- [How to use Sqlite in your application](examples/using-sqlite.md) +- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) ### Examples -- [Example 1: Using Sqlite](examples/using-sqlite.md) -- [Example 2: Packaging zlib](examples/packaging-zlib.md) -- [Example 3: Patching libpng for x86-uwp](examples/patching-libpng.md) +- [Installing and Using Packages Example: sqlite](examples/installing-and-using-packages.md) +- [Packaging Zipfiles Example: zlib](examples/packaging-zipfiles.md) +- [Packaging GitHub Repositories Example: libogg](examples/packaging-github-repos.md) +- [Patching Example: Patching libpng to work for x86-uwp](examples/patching.md) ### User Help diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md index 1aad301eb..f159f7f64 100644 --- a/docs/maintainers/portfile-functions.md +++ b/docs/maintainers/portfile-functions.md @@ -14,6 +14,7 @@ - [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\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)
- [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
- [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
- [vcpkg\_from\_git](vcpkg_from_git.md)
diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md index 104032ffc..4971df960 100644 --- a/docs/maintainers/vcpkg_extract_source_archive.md +++ b/docs/maintainers/vcpkg_extract_source_archive.md @@ -1,6 +1,6 @@ # vcpkg_extract_source_archive -Extract an archive into the source directory. +Extract an archive into the source directory. Deprecated in favor of [`vcpkg_extract_source_archive_ex`](vcpkg_extract_source_archive_ex.md). ## Usage ```cmake diff --git a/docs/maintainers/vcpkg_extract_source_archive_ex.md b/docs/maintainers/vcpkg_extract_source_archive_ex.md new file mode 100644 index 000000000..92c90b296 --- /dev/null +++ b/docs/maintainers/vcpkg_extract_source_archive_ex.md @@ -0,0 +1,52 @@ +# vcpkg_extract_source_archive_ex + +Extract an archive into the source directory. Replaces [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md). + +## Usage +```cmake +vcpkg_extract_source_archive_ex( + OUT_SOURCE_PATH <SOURCE_PATH> + ARCHIVE <${ARCHIVE}> + [REF <1.0.0>] + [NO_REMOVE_ONE_LEVEL] + [WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/src>] + [PATCHES <a.patch>...] +) +``` +## Parameters +### OUT_SOURCE_PATH +Specifies the out-variable that will contain the extracted location. + +This should be set to `SOURCE_PATH` by convention. + +### ARCHIVE +The full path to the archive to be extracted. + +This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md). + +### REF +A friendly name that will be used instead of the filename of the archive. + +By convention, this is set to the version number or tag fetched + +### WORKING_DIRECTORY +If specified, the archive will be extracted into the working directory instead of `${CURRENT_BUILDTREES_DIR}/src/`. + +Note that the archive will still be extracted into a subfolder underneath that directory (`${WORKING_DIRECTORY}/${REF}-${HASH}/`). + +### PATCHES +A list of patches to be applied to the extracted sources. + +Relative paths are based on the port directory. + +### NO_REMOVE_ONE_LEVEL +Specifies that the default removal of the top level folder should not occur. + +## Examples + +* [bzip2](https://github.com/Microsoft/vcpkg/blob/master/ports/bzip2/portfile.cmake) +* [sqlite3](https://github.com/Microsoft/vcpkg/blob/master/ports/sqlite3/portfile.cmake) +* [cairo](https://github.com/Microsoft/vcpkg/blob/master/ports/cairo/portfile.cmake) + +## Source +[scripts/cmake/vcpkg_extract_source_archive_ex.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_extract_source_archive_ex.cmake)
diff --git a/docs/users/integration.md b/docs/users/integration.md index ce52abe23..fbaea41d9 100644 --- a/docs/users/integration.md +++ b/docs/users/integration.md @@ -35,7 +35,7 @@ cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.c ``` Projects configured with the Vcpkg toolchain file will have the appropriate Vcpkg folders added to the cmake search paths. This makes all libraries available to be found through `find_package()`, `find_path()`, and `find_library()`. -See [Example: Using Sqlite](../examples/using-sqlite.md) for a fully worked example using our CMake toolchain. +See [Installing and Using Packages Example: sqlite](../examples/installing-and-using-packages.md) for a fully worked example using our CMake toolchain. Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use `find_path()`, which will correctly work on all platforms: ```cmake |