README.md revision e0197994
150aadb33SDmitri TikhonovLiteSpeed QUIC (LSQUIC) Client Library README
250aadb33SDmitri Tikhonov=============================================
350aadb33SDmitri Tikhonov
450aadb33SDmitri TikhonovDescription
550aadb33SDmitri Tikhonov-----------
650aadb33SDmitri Tikhonov
750aadb33SDmitri TikhonovLiteSpeed QUIC (LSQUIC) Client Library is an open-source implementation
850aadb33SDmitri Tikhonovof QUIC functionality for clients.  It is released in the hope to speed
950aadb33SDmitri Tikhonovthe adoption of QUIC.  Most of the code in this distribution is used in
1050aadb33SDmitri Tikhonovour own products: LiteSpeed Web Server and ADC.  We think it is free of
1150aadb33SDmitri Tikhonovmajor problems.  Nevertheless, do not hesitate to report bugs back to us.
1250aadb33SDmitri TikhonovEven better, send us fixes and improvements!
1350aadb33SDmitri Tikhonov
1450aadb33SDmitri TikhonovCurrently supported QUIC versions are Q035, Q037, Q038, Q039, and Q040.
1550aadb33SDmitri TikhonovSupport for newer versions will be added soon after they are released.
1650aadb33SDmitri TikhonovThe version(s) specified by IETF QUIC WG will be added once the IETF
1750aadb33SDmitri Tikhonovversion of the protocol settles down a little.
1850aadb33SDmitri Tikhonov
1950aadb33SDmitri TikhonovDocumentation
2050aadb33SDmitri Tikhonov-------------
2150aadb33SDmitri Tikhonov
2250aadb33SDmitri TikhonovThe documentation for this module is admittedly sparse.  The API is
2350aadb33SDmitri Tikhonovdocumented in include/lsquic.h.  If you have doxygen, you can run
24e0197994SDmitri Tikhonov`doxygen dox.cfg` or `make docs`.  The example program is
2550aadb33SDmitri Tikhonovtest/http_client.c: a bare-bones, but working, QUIC client.  Have a look
2650aadb33SDmitri Tikhonovin EXAMPLES.txt to see how it can be used.
2750aadb33SDmitri Tikhonov
28e0197994SDmitri TikhonovRequirements
29e0197994SDmitri Tikhonov------------
3050aadb33SDmitri Tikhonov
31e0197994SDmitri TikhonovTo build LSQUIC, you need CMake, zlib, and BoringSSL.  The example program
32e0197994SDmitri Tikhonovuses libevent to provide the event loop.
3350aadb33SDmitri Tikhonov
34e0197994SDmitri TikhonovBuilding BoringSSL
35e0197994SDmitri Tikhonov------------------
36e0197994SDmitri Tikhonov
37e0197994SDmitri TikhonovBoringSSL is not packaged; you have to build it yourself.  The process is
38e0197994SDmitri Tikhonovstraightforward.  You will need `go` installed.
39e0197994SDmitri Tikhonov
40e0197994SDmitri Tikhonov1. Clone BoringSSL by issuing the following command:
41e0197994SDmitri Tikhonov
42e0197994SDmitri Tikhonov```
43e0197994SDmitri Tikhonovgit clone https://boringssl.googlesource.com/boringssl
44e0197994SDmitri Tikhonovcd boringssl
45e0197994SDmitri Tikhonov```
46e0197994SDmitri Tikhonov
47e0197994SDmitri Tikhonov2. Check out stable branch:
48e0197994SDmitri Tikhonov
49e0197994SDmitri Tikhonov```
50e0197994SDmitri Tikhonovgit co chromium-stable
51e0197994SDmitri Tikhonov```
52e0197994SDmitri Tikhonov
53e0197994SDmitri Tikhonov3. Compile the library
54e0197994SDmitri Tikhonov
55e0197994SDmitri Tikhonov```
56e0197994SDmitri Tikhonovcmake . &&  make
57e0197994SDmitri Tikhonov```
58e0197994SDmitri Tikhonov
59e0197994SDmitri TikhonovIf you want to turn on optimizations, do
60e0197994SDmitri Tikhonov
61e0197994SDmitri Tikhonov```
62e0197994SDmitri Tikhonovcmake -DCMAKE_BUILD_TYPE=Release . && make
63e0197994SDmitri Tikhonov```
64e0197994SDmitri Tikhonov
65e0197994SDmitri Tikhonov4. Install the library
66e0197994SDmitri Tikhonov
67e0197994SDmitri TikhonovThis is the manual step.  You will need to copy library files manually.
68e0197994SDmitri TikhonovLSQUIC client library needs two: `ssl/libssl.a` and `crypto/libcrypto.a`.
69e0197994SDmitri TikhonovTo install these in `/usr/local/lib`, you should do the following:
70e0197994SDmitri Tikhonov
71e0197994SDmitri Tikhonov```
72e0197994SDmitri TikhonovBORINGSSL_SOURCE=$PWD
73e0197994SDmitri Tikhonovcd /usr/local/lib
74e0197994SDmitri Tikhonovsudo cp $BORINGSSL_SOURCE/ssl/libssl.a
75e0197994SDmitri Tikhonovsudo cp $BORINGSSL_SOURCE/crypto/libcrypto.a
76e0197994SDmitri Tikhonov```
77e0197994SDmitri Tikhonov
78e0197994SDmitri TikhonovIf you do not want to install the library (or do not have root), you
79e0197994SDmitri Tikhonovcan do this instead:
80e0197994SDmitri Tikhonov
81e0197994SDmitri Tikhonov```
82e0197994SDmitri TikhonovBORINGSSL_SOURCE=$PWD
83e0197994SDmitri Tikhonovmkdir -p $HOME/tmp/boringssl-libs
84e0197994SDmitri Tikhonovcd $HOME/tmp/boringssl-libs
85e0197994SDmitri Tikhonovln -s $BORINGSSL_SOURCE/ssl/libssl.a
86e0197994SDmitri Tikhonovln -s $BORINGSSL_SOURCE/crypto/libcrypto.a
87e0197994SDmitri Tikhonov```
88e0197994SDmitri Tikhonov
89e0197994SDmitri TikhonovBuilding LSQUIC Client Library
90e0197994SDmitri Tikhonov------------------------------
91e0197994SDmitri Tikhonov
92e0197994SDmitri TikhonovLSQUIC's `http_client` and the tests link BoringSSL libraries statically.
93e0197994SDmitri TikhonovFollowing previous section, you can build LSQUIC as follows:
94e0197994SDmitri Tikhonov
95e0197994SDmitri Tikhonov```
96e0197994SDmitri Tikhonovcmake -DBORINGSSL_INCLUDE=$BORINGSSL_SOURCE/include \
97e0197994SDmitri Tikhonov                                -DBORINGSSL_LIB=$HOME/tmp/boringssl-libs .
98e0197994SDmitri Tikhonovmake
99e0197994SDmitri Tikhonov```
100e0197994SDmitri Tikhonov
101e0197994SDmitri TikhonovRun tests:
102e0197994SDmitri Tikhonov
103e0197994SDmitri Tikhonov```
104e0197994SDmitri Tikhonovmake test
105e0197994SDmitri Tikhonov```
106e0197994SDmitri Tikhonov
107e0197994SDmitri TikhonovPlatforms
108e0197994SDmitri Tikhonov---------
109e0197994SDmitri Tikhonov
110e0197994SDmitri TikhonovThe client library has been tested on the following platforms:
111e0197994SDmitri Tikhonov- Linux
112e0197994SDmitri Tikhonov  - x86_64
113e0197994SDmitri Tikhonov  - ARM (Raspberry Pi 3)
114e0197994SDmitri Tikhonov- FreeBSD
115e0197994SDmitri Tikhonov  - i386
116e0197994SDmitri Tikhonov- MacOS
117e0197994SDmitri Tikhonov  - x86_64
11850aadb33SDmitri Tikhonov
11950aadb33SDmitri TikhonovHave fun,
12050aadb33SDmitri Tikhonov
12150aadb33SDmitri TikhonovLiteSpeed QUIC Team.
12250aadb33SDmitri Tikhonov
12350aadb33SDmitri TikhonovCopyright (c) 2017 LiteSpeed Technologies Inc
124