Code layout

The curl source code tree is neither large nor complicated. A key thing toremember is that libcurl is the library and that this library is the biggestcomponent of the curl command-line tool.

root

We try to keep the number of files in the source tree root to a minimum. Youmight see a slight difference in files if you check a release archive comparedto what is stored in the git repository as several files are generated by therelease scripts.

Some of the more notable ones include:

• buildconf: (deprecated) script used to build configure and more whenbuilding curl from source out of the git repository.
• buildconf.bat: the Windows version of buildconf. Run this after havingchecked out the full source code from git.
• CHANGES: generated at release and put into the release archive. Itcontains the 1000 latest changes to the source repository.
• configure: a generated script that is used on Unix-like systems togenerate a setup when building curl.
• COPYING: the license detailing the rules for your using the code.
• GIT-INFO: only present in git and contains information about how tobuild curl after having checked out the code from git.
• maketgz: the script used to produce release archives and daily snapshots
• README: a short summary of what curl and libcurl are.
• RELEASE-NOTES: contains the changes done for the latest release; whenfound in git it contains the changes done since the previous release thatare destined to end up in the coming release.

lib

This directory contains the full source code for libcurl. It is the samesource code for all platforms—over one hundred C source files and a few moreprivate header files. The header files used when building applications againstlibcurl are not stored in this directory; see include/curl for those.

Depending on what features are enabled in your own build and whatfunctions your platform provides, some of the source files or portions of thesource files may contain code that is not used in your particular build.

lib/vtls

The VTLS sub section within libcurl is the home of all the TLS backendslibcurl can be built to support. The "virtual" TLS internal API is a backendagnostic API used internally to access TLS and crypto functions without themain code knowing which specific TLS library is used. This allows the personwho builds libcurl to select from a wide variety of TLS libraries to build with.

We also maintain aSSL comparisontable on the website to aidusers.

• AmiSSL: an OpenSSL fork made for AmigaOS (usesopenssl.c)
• BearSSL
• BoringSSL: an OpenSSL fork maintained by Google. (usesopenssl.c)
• GnuTLS
• LibreSSL: an OpenSSL fork maintained by the OpenBSD team. (usesopenssl.c)
• mbedTLS
• OpenSSL
• rustls: a TLS library written in rust
• Schannel: the native TLS library on Windows.
• Secure Transport: the native TLS library on macOS
• wolfSSL

src

This directory holds the source code for the curl command-line tool. It is thesame source code for all platforms that run the tool.

Most of what the command-line tool does is to convert given command lineoptions into the corresponding libcurl options or set of options and then makessure to issue them correctly to drive the network transfer according to theuser's wishes.

This code uses libcurl just as any other application would.

include/curl

Here are the public header files that are provided for libcurl-usingapplications. Some of them are generated at configure or release time so theydo not look identical in the git repository as they do in a release archive.

With modern libcurl, all an application is expected to include in its C source codeis#include <curl/curl.h>

docs

The main documentation location. Text files in this directory are typicallyplain text files. We have slowly started to move towards Markdown format so afew (but growing number of) files use the.md extension to signify that.

Most of these documents are also shown on the curl website automaticallyconverted from text to a web friendly format/look.

• BINDINGS: lists all known libcurl language bindings and where to find them
• BUGS: how to report bugs and where
• CODE_OF_CONDUCT.md: how we expect people to behave in this project
• CONTRIBUTE: what to think about when contributing to the project
• curl.1: the curl command-line tool man page, in nroff format
• curl-config.1: the curl-config man page, in nroff format
• FAQ: frequently asked questions about various curl-related subjects
• FEATURES: an incomplete list of curl features
• HISTORY: describes how the project started and has evolved over the years
• HTTP2.md: how to use HTTP/2 with curl and libcurl
• HTTP-COOKIES: how curl supports and works with HTTP cookies
• index.html: a basic HTML page as a documentation index page
• INSTALL: how to build and install curl and libcurl from source
• INSTALL.cmake: how to build curl and libcurl with CMake
• INSTALL.devcpp: how to build curl and libcurl with devcpp
• INTERNALS: details curl and libcurl internal structures
• KNOWN_BUGS: list of known bugs and problems
• LICENSE-MIXING: describes how to combine different third party modules andtheir individual licenses
• MAIL-ETIQUETTE: this is how to communicate on our mailing lists
• MANUAL: a tutorial-like guide on how to use curl
• mk-ca-bundle.1: the mk-ca-bundle tool man page, in nroff format
• README.cmake: CMake details
• README.netware: Netware details
• README.win32: win32 details
• RELEASE-PROCEDURE: how to do a curl and libcurl release
• RESOURCES: further resources for further reading on what, why and how curldoes things
• ROADMAP.md: what we want to work on in the future
• SECURITY: how we work on security vulnerabilities
• SSLCERTS: TLS certificate handling documented
• SSL-PROBLEMS: common SSL problems and their causes
• THANKS: thanks to this extensive list of friendly people, curl exists today.
• TheArtOfHttpScripting: a tutorial into HTTP scripting with curl
• TODO: things we or you can work on implementing
• VERSIONS: how the version numbering of libcurl works

docs/libcurl

All libcurl functions have their own man pages in individual files with .3extensions, using nroff format, in this directory. There are also a few otherfiles that are described below.

• ABI
• index.html
• libcurl.3
• libcurl-easy.3
• libcurl-errors.3
• libcurl.m4
• libcurl-multi.3
• libcurl-share.3
• libcurl-thread.3
• libcurl-tutorial.3
• symbols-in-versions

docs/libcurl/opts

This directory contains the man pages for the individual options for threedifferent libcurl functions.

curl_easy_setopt() options start withCURLOPT_,curl_multi_setopt() options start withCURLMOPT_ andcurl_easy_getinfo() options start withCURLINFO_.

docs/examples

Contains around 100 stand-alone examples that are meant to help readersunderstand how libcurl can be used.

See also thelibcurl examples section of this book.

scripts

Handy scripts.

• contributors.sh: extracts all contributors from the git repository since agiven hash/tag. The purpose is to generate a list for the RELEASE-NOTES fileand to allow manually added names to remain in there even on updates. Thescript uses theTHANKS-filter file to rewrite some names.
• contrithanks.sh: extracts contributors from the git repository since agiven hash/tag, filters out all the names that are already mentioned inTHANKS, and then outputsTHANKS to stdout with the list of newcontributors appended at the end; it is meant to allow easier updates of theTHANKS document. The script uses theTHANKS-filter file to rewrite somenames.
• log2changes.pl: generates theCHANGES file for releases, as used by therelease script. It simply converts git log output.
• zsh.pl: helper script to provide curl command-line completions to users ofthe zsh shell.