BUILD-WINDOWS.md revision 8573794b 
1LiteSpeed QUIC (LSQUIC) Client Library - Building for Windows
2=============================================================
3
4Description
5-----------
6
7This document is intended to supplement the document README.md at the
8root of the distribution of the LiteSpeed QUIC (LSQUIC) Client Library
9to build the library and programs in a Windows environment.  
10
11The addition of Windows support to the LSQUIC Client was a contribution 
12from the user community and this document was based on our experiences
13of validating the code.  As for the overall implementation, do not hesitate
14to report bugs back to us.  Even better, continue to send us fixes and 
15improvements - it makes the code better for everyone.
16
17
18Preliminaries
19-------------
20It it recommended that the installer have experience with Windows development,
21Visual Studio, and open source projects in Windows.  These instructions assume
22a general build, primarily for 64-bit, both of a debug and a release version.
23
24Some open source code required to be installed to build the code include:
25   - The [Git version control system executable for Windows](https://git-scm.com/download/win).
26   - A version of the Visual Studio development environment for Windows.  
27     The Windows SDK and C++ must be installed from it.  The 
28     [Visual Studio Community Edition](https://www.visualstudio.com/thank-you-downloading-visual-studio) will be just fine.
29   - [cmake for Windows](https://cmake.org/download/).  Download and install the 
30     version appropriate for the development/target platform (32 vs 64-bits, 
31     etc.).
32   - The Windows vcpkg package manager.  It can be cloned from [here](https://github.com/Microsoft/vcpkg).
33     Clone it at the same level to be used to clone/develop the lsquic-client.
34     The package must be compiled following the instructions on the git 
35     repository.
36   - Perform builds using the _Developer Command Prompt for Visual Studio_ instead
37     of the regular `cmd.exe`.
38   - Once the package manager has been built, it must be used to install
39     and build some open source projects.  Before doing that, an environment 
40     variable must be defined which specifies how the package should be built.
41     The easiest way would be to add it into the system environment variables
42     in the System applet of the Windows Control Panel.  This example assumes 
43     64-bit static libraries will be built, which is what is generally 
44     recommended:
45        ```
46        VCPKG_DEFAULT_TRIPLET=x64-windows-static
47        ```
48   - From the command line, once the variable above has been defined, install
49     both *zlib* and *libevent*.  Note that libevent may also automatically 
50     install *openssl*.  If it does not, it may need to be manually specified 
51     to properly link the lsquic-client executables.
52        ```
53        vcpkg install zlib:x64-windows-static
54        vcpkg install libevent:x64-windows-static
55        vcpkg integrate install
56        ```
57   - Clone and compile boringssl.  It can be cloned from [here](https://boringssl.googlesource.com/boringssl).
58   
59        ```
60        git clone https://boringssl.googlesource.com/boringssl
61        cd boringssl
62        cmake -DCMAKE_GENERATOR_PLATFORM=x64 --config Debug -DBUILD_SHARED_LIBS=OFF -DOPENSSL_NO_ASM=1 .
63        msbuild ALL_BUILD.vcxproj
64        set boringssl=%cd%
65        ```
66   - Visual Studio can be run, and the project opened within the boringssl
67     directory.  Set the solution configuration to *Debug* and the solution 
68     platform to *64-bit*.  Compile the project.
69   - Repeat the cmake and compile steps replacing *Debug* with *Release*.
70
71Make and Compile LSQUIC-Client
72------------------------------
73
74
75Clone lsquic-client:
76
77   ```
78   git clone https://github.com/litespeedtech/lsquic-client.git --recurse-submodules
79   cd lsquic-client
80   ```
81
82Configure the build using cmake (you can specify `Release` instead of `Debug`
83to build an optimized version of the library, but that won't build tests):
84
85   ```
86   cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DBUILD_SHARED_LIBS=OFF ^
87        -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_BUILD_TYPE=Debug ^
88        -DCMAKE_TOOLCHAIN_FILE=c:/tools/vcpkg/scripts/buildsystems/vcpkg.cmake ^
89        -DBORINGSSL_DIR=%boringssl% .
90   ```
91
92Compile everything (add `/m` flag if you have processors to spare):
93
94   ```
95   msbuild ALL_BUILD.vcxproj
96   ```
97
98`http_client.exe` should be found in the `Debug` (or `Release`) directory.
99   
100Run tests (assuming `Debug` build):
101
102   ```
103   msbuild RUN_TESTS.vcxproj
104   ```
105
106Have fun,
107
108LiteSpeed QUIC Team.
109
110Copyright (c) 2017 - 2019 LiteSpeed Technologies Inc
111