README.md revision 2e1429b4
15392f7a3SLiteSpeed Tech[![Build Status](https://travis-ci.org/litespeedtech/lsquic.svg?branch=master)](https://travis-ci.org/litespeedtech/lsquic)
25392f7a3SLiteSpeed Tech[![Build Status](https://api.cirrus-ci.com/github/litespeedtech/lsquic.svg)](https://cirrus-ci.com/github/litespeedtech/lsquic)
3f50b9148SDmitri Tikhonov[![Build status](https://ci.appveyor.com/api/projects/status/ij4n3vy343pkgm1j?svg=true)](https://ci.appveyor.com/project/litespeedtech/lsquic)
41fc8f998SDmitri Tikhonov
55392f7a3SLiteSpeed TechLiteSpeed QUIC (LSQUIC) Library README
650aadb33SDmitri Tikhonov=============================================
750aadb33SDmitri Tikhonov
850aadb33SDmitri TikhonovDescription
950aadb33SDmitri Tikhonov-----------
1050aadb33SDmitri Tikhonov
115392f7a3SLiteSpeed TechLiteSpeed QUIC (LSQUIC) Library is an open-source implementation of QUIC
12f87fb49cSDmitri Tikhonovand HTTP/3 functionality for servers and clients.  Most of the code in this
13f87fb49cSDmitri Tikhonovdistribution is used in our own products: LiteSpeed Web Server, LiteSpeed ADC,
14f87fb49cSDmitri Tikhonovand OpenLiteSpeed.  We think it is free of major problems.  Nevertheless, do
15f87fb49cSDmitri Tikhonovnot hesitate to report bugs back to us.  Even better, send us fixes and
16f87fb49cSDmitri Tikhonovimprovements!
1750aadb33SDmitri Tikhonov
18b1a7c3f9SDmitri TikhonovCurrently supported QUIC versions are Q043, Q046, Q050, ID-27, ID-28, ID-29,
19b1a7c3f9SDmitri Tikhonovand ID-30.  Support for newer versions will be added soon after they are
20b1a7c3f9SDmitri Tikhonovreleased.
2150aadb33SDmitri Tikhonov
2250aadb33SDmitri TikhonovDocumentation
2350aadb33SDmitri Tikhonov-------------
2450aadb33SDmitri Tikhonov
25a5fa05f9SDmitri TikhonovDocumentation is available at https://lsquic.readthedocs.io/en/latest/.
26a5fa05f9SDmitri Tikhonov
27a5fa05f9SDmitri TikhonovIn addition, see example programs for API usage and EXAMPLES.txt for
28a5fa05f9SDmitri Tikhonovsome compilation and run-time options.
2950aadb33SDmitri Tikhonov
30e0197994SDmitri TikhonovRequirements
31e0197994SDmitri Tikhonov------------
3250aadb33SDmitri Tikhonov
33e0197994SDmitri TikhonovTo build LSQUIC, you need CMake, zlib, and BoringSSL.  The example program
34e0197994SDmitri Tikhonovuses libevent to provide the event loop.
3550aadb33SDmitri Tikhonov
36e0197994SDmitri TikhonovBuilding BoringSSL
37e0197994SDmitri Tikhonov------------------
38e0197994SDmitri Tikhonov
39e0197994SDmitri TikhonovBoringSSL is not packaged; you have to build it yourself.  The process is
40e0197994SDmitri Tikhonovstraightforward.  You will need `go` installed.
41e0197994SDmitri Tikhonov
42e0197994SDmitri Tikhonov1. Clone BoringSSL by issuing the following command:
43e0197994SDmitri Tikhonov
44e0197994SDmitri Tikhonov```
45e0197994SDmitri Tikhonovgit clone https://boringssl.googlesource.com/boringssl
46e0197994SDmitri Tikhonovcd boringssl
47e0197994SDmitri Tikhonov```
48e0197994SDmitri Tikhonov
495392f7a3SLiteSpeed TechYou may need to install pre-requisites like zlib and libevent.
50e0197994SDmitri Tikhonov
51c38e7df7SDmitri Tikhonov2. Use specific BoringSSL version
52c38e7df7SDmitri Tikhonov
53c38e7df7SDmitri Tikhonov```
54f913a297SDmitri Tikhonovgit checkout 251b5169fd44345f455438312ec4e18ae07fd58c
55c38e7df7SDmitri Tikhonov```
56c38e7df7SDmitri Tikhonov
574947ba95SDmitri Tikhonov3. Compile the library
58e0197994SDmitri Tikhonov
59e0197994SDmitri Tikhonov```
60e0197994SDmitri Tikhonovcmake . &&  make
61e0197994SDmitri Tikhonov```
62e0197994SDmitri Tikhonov
63199c01abSLiteSpeed TechRemember where BoringSSL sources are:
64e0197994SDmitri Tikhonov```
65199c01abSLiteSpeed TechBORINGSSL=$PWD
66e0197994SDmitri Tikhonov```
67e0197994SDmitri Tikhonov
68199c01abSLiteSpeed TechIf you want to turn on optimizations, do
69e0197994SDmitri Tikhonov
70e0197994SDmitri Tikhonov```
71199c01abSLiteSpeed Techcmake -DCMAKE_BUILD_TYPE=Release . && make
72e0197994SDmitri Tikhonov```
73e0197994SDmitri Tikhonov
74038a9441SAaron FranceIf you want to build as a library, (necessary to build lsquic itself
75038a9441SAaron Franceas as shared library) do:
76038a9441SAaron France
77038a9441SAaron France```
78038a9441SAaron Francecmake -DBUILD_SHARED_LIBS=1 . && make
79038a9441SAaron France```
80038a9441SAaron France
815392f7a3SLiteSpeed TechBuilding LSQUIC Library
825392f7a3SLiteSpeed Tech-----------------------
83e0197994SDmitri Tikhonov
845392f7a3SLiteSpeed TechLSQUIC's `http_client`, `http_server`, and the tests link BoringSSL
855392f7a3SLiteSpeed Techlibraries statically.  Following previous section, you can build LSQUIC
865392f7a3SLiteSpeed Techas follows:
87e0197994SDmitri Tikhonov
8867b0dc15SDmitri Tikhonov1. Get the source code
8967b0dc15SDmitri Tikhonov
9067b0dc15SDmitri Tikhonov```
915392f7a3SLiteSpeed Techgit clone https://github.com/litespeedtech/lsquic.git
925392f7a3SLiteSpeed Techcd lsquic
935392f7a3SLiteSpeed Techgit submodule init
945392f7a3SLiteSpeed Techgit submodule update
9567b0dc15SDmitri Tikhonov```
9667b0dc15SDmitri Tikhonov
9767b0dc15SDmitri Tikhonov2. Compile the library
9867b0dc15SDmitri Tikhonov
99038a9441SAaron FranceStatically:
100038a9441SAaron France
10167b0dc15SDmitri Tikhonov
102e0197994SDmitri Tikhonov```
103199c01abSLiteSpeed Tech# $BORINGSSL is the top-level BoringSSL directory from the previous step
104199c01abSLiteSpeed Techcmake -DBORINGSSL_DIR=$BORINGSSL .
105e0197994SDmitri Tikhonovmake
106e0197994SDmitri Tikhonov```
107e0197994SDmitri Tikhonov
108038a9441SAaron FranceAs a dynamic library:
109038a9441SAaron France
110038a9441SAaron France```
1112e1429b4SDmitri Tikhonovcmake -DLSQUIC_SHARED_LIB=1 -DBORINGSSL_DIR=$BORINGSSL .
112038a9441SAaron Francemake
113038a9441SAaron France```
114038a9441SAaron France
115038a9441SAaron France
11667b0dc15SDmitri Tikhonov3. Run tests
117e0197994SDmitri Tikhonov
118e0197994SDmitri Tikhonov```
119e0197994SDmitri Tikhonovmake test
120e0197994SDmitri Tikhonov```
121e0197994SDmitri Tikhonov
122306ecefeSBrian ProdoehlBuilding with Docker
123306ecefeSBrian Prodoehl---------
12427187418SLiteSpeed TechThe library and the example client and server can be built with Docker.
12527187418SLiteSpeed Tech
12627187418SLiteSpeed TechInitialize Git submodules:
12727187418SLiteSpeed Tech```
12827187418SLiteSpeed Techcd lsquic
12927187418SLiteSpeed Techgit submodule init
13027187418SLiteSpeed Techgit submodule update
13127187418SLiteSpeed Tech```
13227187418SLiteSpeed Tech
13327187418SLiteSpeed TechBuild the Docker image:
134306ecefeSBrian Prodoehl```
1355392f7a3SLiteSpeed Techdocker build -t lsquic .
136306ecefeSBrian Prodoehl```
137306ecefeSBrian Prodoehl
13827187418SLiteSpeed TechThen you can use the examples from the command line.  For example:
139306ecefeSBrian Prodoehl```
14027187418SLiteSpeed Techsudo docker run -it --rm lsquic http_client -s www.google.com  -p / -o version=Q046
14127187418SLiteSpeed Techsudo docker run -p 12345:12345/udp -v /path/to/certs:/mnt/certs -it --rm lsquic http_server -c www.example.com,/mnt/certs/chain,/mnt/certs/key
142306ecefeSBrian Prodoehl```
143306ecefeSBrian Prodoehl
144e0197994SDmitri TikhonovPlatforms
145e0197994SDmitri Tikhonov---------
146e0197994SDmitri Tikhonov
1475392f7a3SLiteSpeed TechThe library has been tested on the following platforms:
148e0197994SDmitri Tikhonov- Linux
149aff2a1d8SDmitri Tikhonov  - i386
150e0197994SDmitri Tikhonov  - x86_64
151e0197994SDmitri Tikhonov  - ARM (Raspberry Pi 3)
152e0197994SDmitri Tikhonov- FreeBSD
153e0197994SDmitri Tikhonov  - i386
154e0197994SDmitri Tikhonov- MacOS
155e0197994SDmitri Tikhonov  - x86_64
1569a690580SDmitri Tikhonov- Android
1579a690580SDmitri Tikhonov  - ARM
158fb3e20e0SDmitri Tikhonov- Windows
1595392f7a3SLiteSpeed Tech  - x86_64
16050aadb33SDmitri Tikhonov
16150aadb33SDmitri TikhonovHave fun,
16250aadb33SDmitri Tikhonov
16350aadb33SDmitri TikhonovLiteSpeed QUIC Team.
16450aadb33SDmitri Tikhonov
165740e26dcSJoshua ReynoldsCopyright (c) 2017 - 2020 LiteSpeed Technologies Inc
166