BUILD-WINDOWS.md revision 1e75f938 
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   - Once the package manager has been built, it must be used to install
37     and build some open source projects.  Before doing that, an environment 
38     variable must be defined which specifies how the package should be built.
39     The easiest way would be to add it into the system environment variables
40     in the System applet of the Windows Control Panel.  This example assumes 
41     64-bit static libraries will be built, which is what is generally 
42     recommended:
43        ```
44        VCPKG_DEFAULT_TRIPLET=x64-windows-static
45        ```
46   - From the command line, once the variable above has been defined, install
47     both *zlib* and *libevent*.  Note that libevent may also automatically 
48     install *openssl*.  If it does not, it may need to be manually specified 
49     to properly link the lsquic-client executables.
50        ```
51        vcpkg install zlib
52        vcpkg install libevent
53        ```
54   - Clone and compile boringssl.  It can be cloned from [here](https://boringssl.googlesource.com/boringssl) 
55     and should be cloned at the same level to be used to clone/develop 
56     the lsquic-client.  Once cloned, cmake must be run to create the projects 
57     (the dot at the end of the line is required):
58        ```
59        cmake -DCMAKE_GENERATOR_PLATFORM=x64 --config Debug -DBUILD_SHARED_LIBS=OFF -DOPENSSL_NO_ASM=1 .
60        ```
61   - Visual Studio can be run, and the project opened within the boringssl
62     directory.  Set the solution configuration to *Debug* and the solution 
63     platform to *64-bit*.  Compile the project.
64   - Repeat the cmake and compile steps replacing *Debug* with *Release*.
65
66Make and Compile LSQUIC-Client
67------------------------------
68
69The LSQUIC-Client for Windows is currently housed on the master branch.  
70To check it out specify (from the directory where the code will be housed):
71   ```
72   git clone https://github.com/litespeedtech/lsquic-client.git
73   cd lsquic-client
74   git checkout master
75   ```
76
77cmake must be run to prepare to build the software in the top level
78cloned directory.  The dot at the end is required.  Begin with the debug
79version as it includes all of the programs.
80   ```
81   cmake -DCMAKE_GENERATOR_PLATFORM=x64 --config Debug -DBUILD_SHARED_LIBS=OFF
82   ```
83
84Visual Studio can now be brought up, and there will be projects in the
85cloned directory.  The ALL_BUILD project will build the full project.
86Make sure the solution configuration is set to *Debug*.  The project may
87need to be built twice as the first time some of the compiles will fail
88as the lsquic.lib library has not completed building in the first attempt.
89
90Both the debug and optmized versions can co-exist in the same 
91environment as they are compiled to different directories.
92
93To build the optimized version, repeat the process above with a slightly
94different cmake command:
95   ```
96   cmake -DCMAKE_GENERATOR_PLATFORM=x64 --config Release -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release .
97   ```
98
99After cmake has finished, you can open the project, set the solution 
100configuration to *Release* and build the ALL_BUILD project.  There are 
101many fewer programs in the optimized version.
102
103Have fun,
104
105LiteSpeed QUIC Team.
106
107Copyright (c) 2017-2018 LiteSpeed Technologies Inc
108