From 077b7f1378537478ec97a57af664ebba2efc0c86 Mon Sep 17 00:00:00 2001
From: Simon Brand <tartanllama@gmail.com>
Date: Fri, 16 Nov 2018 11:24:19 +0000
Subject: Add packaging GitHub repo example

---
 docs/about/faq.md                       |  2 +-
 docs/examples/packaging-github-repos.md | 59 +++++++++++++++++++++++++++++++++
 docs/index.md                           |  1 +
 3 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/packaging-github-repos.md

(limited to 'docs')

diff --git a/docs/about/faq.md b/docs/about/faq.md
index 57b908f48..b7c9d67c8 100644
--- a/docs/about/faq.md
+++ b/docs/about/faq.md
@@ -10,7 +10,7 @@ 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 our [packaging example](../examples/packaging-zipfiles.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.
 
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/index.md b/docs/index.md
index d7b104ebc..69dbdcd1e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -8,6 +8,7 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 
 - [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
-- 
cgit v1.2.3