README.md revision da710add 
1LiteSpeed QUIC (LSQUIC) Client Library README
2=============================================
3
4Description
5-----------
6
7LiteSpeed QUIC (LSQUIC) Client Library is an open-source implementation
8of QUIC functionality for clients.  It is released in the hope to speed
9the adoption of QUIC.  Most of the code in this distribution is used in
10our own products: LiteSpeed Web Server and ADC.  We think it is free of
11major problems.  Nevertheless, do not hesitate to report bugs back to us.
12Even better, send us fixes and improvements!
13
14Currently supported QUIC versions are Q035, Q037, Q038, Q039, and Q041.
15Support for newer versions will be added soon after they are released.
16The version(s) specified by IETF QUIC WG will be added once the IETF
17version of the protocol settles down a little.
18
19Documentation
20-------------
21
22The documentation for this module is admittedly sparse.  The API is
23documented in include/lsquic.h.  If you have doxygen, you can run
24`doxygen dox.cfg` or `make docs`.  The example program is
25test/http_client.c: a bare-bones, but working, QUIC client.  Have a look
26in EXAMPLES.txt to see how it can be used.
27
28Requirements
29------------
30
31To build LSQUIC, you need CMake, zlib, and BoringSSL.  The example program
32uses libevent to provide the event loop.
33
34Building BoringSSL
35------------------
36
37BoringSSL is not packaged; you have to build it yourself.  The process is
38straightforward.  You will need `go` installed.
39
401. Clone BoringSSL by issuing the following command:
41
42```
43git clone https://boringssl.googlesource.com/boringssl
44cd boringssl
45```
46
472. Check out stable branch:
48
49```
50git checkout chromium-stable
51```
52
533. Compile the library
54
55```
56cmake . &&  make
57```
58
59If you want to turn on optimizations, do
60
61```
62cmake -DCMAKE_BUILD_TYPE=Release . && make
63```
64
654. Install the library
66
67This is the manual step.  You will need to copy library files manually.
68LSQUIC client library needs two: `ssl/libssl.a` and `crypto/libcrypto.a`.
69To install these in `/usr/local/lib`, you should do the following:
70
71```
72BORINGSSL_SOURCE=$PWD
73cd /usr/local/lib
74sudo cp $BORINGSSL_SOURCE/ssl/libssl.a .
75sudo cp $BORINGSSL_SOURCE/crypto/libcrypto.a .
76```
77
78If you do not want to install the library (or do not have root), you
79can do this instead:
80
81```
82BORINGSSL_SOURCE=$PWD
83mkdir -p $HOME/tmp/boringssl-libs
84cd $HOME/tmp/boringssl-libs
85ln -s $BORINGSSL_SOURCE/ssl/libssl.a
86ln -s $BORINGSSL_SOURCE/crypto/libcrypto.a
87```
88
89Building LSQUIC Client Library
90------------------------------
91
92LSQUIC's `http_client` and the tests link BoringSSL libraries statically.
93Following previous section, you can build LSQUIC as follows:
94
951. Get the source code
96
97```
98git clone https://github.com/litespeedtech/lsquic-client.git
99cd lsquic-client
100```
101
1022. Compile the library
103
104
105```
106cmake -DBORINGSSL_INCLUDE=$BORINGSSL_SOURCE/include \
107                                -DBORINGSSL_LIB=$HOME/tmp/boringssl-libs .
108make
109```
110
1113. Run tests
112
113```
114make test
115```
116
117Building with Docker
118---------
119The library and http_client example can be built with Docker.
120```
121docker build -t lsquic-client .
122```
123
124Then you can use the http_client example from the command line.
125```
126docker run -it --rm lsquic-client http_client -H www.google.com -s 74.125.22.106:443 -p /
127```
128
129Platforms
130---------
131
132The client library has been tested on the following platforms:
133- Linux
134  - x86_64
135  - ARM (Raspberry Pi 3)
136- FreeBSD
137  - i386
138- Windows
139  - x86_64
140- MacOS
141  - x86_64
142
143Have fun,
144
145LiteSpeed QUIC Team.
146
147Copyright (c) 2017 LiteSpeed Technologies Inc
148