Code layout

The curl source code tree is neither large nor complicated. A key thing to remember is, perhaps, that libcurl is the library and that library is the biggest component of the curl command-line tool.

root

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

Some of the more notable ones include:

lib

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

Depending on what features are enabled in your own build and what functions your platform provides, some of the source files or portions of the source 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 backends libcurl can be built to support. The “virtual” TLS internal API is a common API that is used within libcurl to access TLS and crypto functions without the main code knowing exactly which TLS library that is used. This allows the person who builds libcurl to select from a wide variety TLS libraries to build with.

We also maintain a SSL comparison table on the web site to aid users.

src

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

Most of what the command-line tool does is to convert given command line options into the corresponding libcurl options or set of options and then makes sure to issue them correctly to drive the network transfer according to the user’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-using applications. Some of them are generated at configure or release time so they do 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 code is #include <curl/curl.h>

docs

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

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

docs/libcurl

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

docs/libcurl/opts

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

curl_easy_setopt() options start with CURLOPT_, curl_multi_setopt() options start with CURLMOPT_ and curl_easy_getinfo() options start with CURLINFO_.

docs/examples

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

See also the libcurl examples section of this book.

scripts

Handy scripts.