Merge pull request #4746 from TartanLlama/master

Rename example documents and add GitHub packaging example

README.md

@@ -37,7 +37,7 @@ The best way to use installed libraries with CMake is via the toolchain file `sc
 
 In Visual Studio, you can create a New Project (or open an existing one). All installed libraries are immediately ready to be `#include`'d and used in your project without additional configuration.
 
-For more information, see our [using a package](docs/examples/using-sqlite.md) example for the specifics.
+For more information, see our [using a package](docs/examples/installing-and-using-packages.md) example for the specifics.
 
 Additional notes on macOS and Linux support can be found in the [official announcement](https://blogs.msdn.microsoft.com/vcblog/2018/04/24/announcing-a-single-c-library-manager-for-linux-macos-and-windows-vcpkg/).
 
@@ -50,7 +50,7 @@ and restart Powershell.
 
 
 ## Examples
-See the [documentation](docs/index.md) for specific walkthroughs, including [using a package](docs/examples/using-sqlite.md) and [adding a new package](docs/examples/packaging-zlib.md).
+See the [documentation](docs/index.md) for specific walkthroughs, including [installing and using a package](docs/examples/installing-and-using-packages.md), [adding a new package from a zipfile](docs/examples/packaging-zipfiles.md), and [adding a new package from a GitHub repo](docs/examples/packaging-github-repos.md).
 
 Our docs are now also available online at ReadTheDocs: <https://vcpkg.readthedocs.io/>!
 

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.

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`.
 

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

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.

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:

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
 

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