Commit f3e0f071 authored by Viktor Szakats's avatar Viktor Szakats
Browse files

docs: Markdown and misc improvements [ci skip]

Approved-by: Daniel Stenberg
Closes #3896
parent 196ae604
Loading
Loading
Loading
Loading
+7 −3
Original line number Original line Diff line number Diff line
@@ -271,7 +271,8 @@ When specifying multiple cipher names, separate them with colon (`:`).


## GSKit
## GSKit


Ciphers are internally defined as numeric codes (https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/apis/gsk_attribute_set_buffer.htm),
Ciphers are internally defined as
[numeric codes](https://www.ibm.com/support/knowledgecenter/ssw_ibm_i_73/apis/gsk_attribute_set_buffer.htm),
but libcurl maps them to the following case-insensitive names.
but libcurl maps them to the following case-insensitive names.


### SSL2 cipher suites (insecure: disabled by default)
### SSL2 cipher suites (insecure: disabled by default)
@@ -446,9 +447,12 @@ but libcurl maps them to the following case-insensitive names.
`DHE-PSK-CHACHA20-POLY1305`,
`DHE-PSK-CHACHA20-POLY1305`,
`EDH-RSA-DES-CBC3-SHA`,
`EDH-RSA-DES-CBC3-SHA`,


## WinSSL
## Schannel


WinSSL allows the enabling and disabling of encryption algorithms, but not specific ciphersuites. They are defined by Microsoft (https://msdn.microsoft.com/en-us/library/windows/desktop/aa375549(v=vs.85).aspx)
Schannel allows the enabling and disabling of encryption algorithms, but not
specific ciphersuites. They are
[defined](https://docs.microsoft.com/windows/desktop/SecCrypto/alg-id) by
Microsoft.


`CALG_MD2`,
`CALG_MD2`,
`CALG_MD4`,
`CALG_MD4`,
+3 −3
Original line number Original line Diff line number Diff line
@@ -9,8 +9,8 @@ style is more important than individual contributors having their own personal
tastes satisfied.
tastes satisfied.


Our C code has a few style rules. Most of them are verified and upheld by the
Our C code has a few style rules. Most of them are verified and upheld by the
"lib/checksrc.pl" script. Invoked with "make checksrc" or even by default by
`lib/checksrc.pl` script. Invoked with `make checksrc` or even by default by
the build system when built after "./configure --enable-debug" has been used.
the build system when built after `./configure --enable-debug` has been used.


It is normally not a problem for anyone to follow the guidelines, as you just
It is normally not a problem for anyone to follow the guidelines, as you just
need to copy the style already used in the source code and there are no
need to copy the style already used in the source code and there are no
@@ -227,7 +227,7 @@ Align with the "current open" parenthesis:
Use **#ifdef HAVE_FEATURE** to do conditional code. We avoid checking for
Use **#ifdef HAVE_FEATURE** to do conditional code. We avoid checking for
particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE
particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE
shall be generated by the configure script for unix-like systems and they are
shall be generated by the configure script for unix-like systems and they are
hard-coded in the config-[system].h files for the others.
hard-coded in the `config-[system].h` files for the others.


We also encourage use of macros/functions that possibly are empty or defined
We also encourage use of macros/functions that possibly are empty or defined
to constants when libcurl is built without that feature, to make the code
to constants when libcurl is built without that feature, to make the code
+27 −27
Original line number Original line Diff line number Diff line
@@ -64,7 +64,7 @@ have OpenSSL installed in your system, you can run configure like this:
   ./configure --without-ssl
   ./configure --without-ssl


If you have OpenSSL installed, but with the libraries in one place and the
If you have OpenSSL installed, but with the libraries in one place and the
header files somewhere else, you have to set the LDFLAGS and CPPFLAGS
header files somewhere else, you have to set the `LDFLAGS` and `CPPFLAGS`
environment variables prior to running configure.  Something like this should
environment variables prior to running configure.  Something like this should
work:
work:


@@ -121,9 +121,9 @@ libressl.
 KB140584 is a must for any Windows developer. Especially important is full
 KB140584 is a must for any Windows developer. Especially important is full
 understanding if you are not going to follow the advice given above.
 understanding if you are not going to follow the advice given above.


 - [How To Use the C Run-Time](https://support.microsoft.com/kb/94248/en-us)
 - [How To Use the C Run-Time](https://support.microsoft.com/help/94248/how-to-use-the-c-run-time)
 - [Run-Time Library Compiler Options](https://docs.microsoft.com/en-us/cpp/build/reference/md-mt-ld-use-run-time-library)
 - [Run-Time Library Compiler Options](https://docs.microsoft.com/cpp/build/reference/md-mt-ld-use-run-time-library)
 - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://msdn.microsoft.com/en-us/library/ms235460)
 - [Potential Errors Passing CRT Objects Across DLL Boundaries](https://docs.microsoft.com/cpp/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries)


If your app is misbehaving in some strange way, or it is suffering from
If your app is misbehaving in some strange way, or it is suffering from
memory corruption, before asking for further help, please try first to
memory corruption, before asking for further help, please try first to
@@ -148,7 +148,7 @@ make targets available to build libcurl with more features, use:
   and SSPI support.
   and SSPI support.


If you have any problems linking libraries or finding header files, be sure
If you have any problems linking libraries or finding header files, be sure
to verify that the provided "Makefile.m32" files use the proper paths, and
to verify that the provided `Makefile.m32` files use the proper paths, and
adjust as necessary. It is also possible to override these paths with
adjust as necessary. It is also possible to override these paths with
environment variables, for example:
environment variables, for example:


@@ -172,8 +172,8 @@ If you want to enable LDAPS support then set LDAPS=1.
## Cygwin
## Cygwin


Almost identical to the unix installation. Run the configure script in the
Almost identical to the unix installation. Run the configure script in the
curl source tree root with `sh configure`. Make sure you have the sh
curl source tree root with `sh configure`. Make sure you have the `sh`
executable in /bin/ or you'll see the configure fail toward the end.
executable in `/bin/` or you'll see the configure fail toward the end.


Run `make`
Run `make`


@@ -200,9 +200,9 @@ protocols:


If you want to set any of these defines you have the following options:
If you want to set any of these defines you have the following options:


 - Modify lib/config-win32.h
 - Modify `lib/config-win32.h`
 - Modify lib/curl_setup.h
 - Modify `lib/curl_setup.h`
 - Modify winbuild/Makefile.vc
 - Modify `winbuild/Makefile.vc`
 - Modify the "Preprocessor Definitions" in the libcurl project
 - Modify the "Preprocessor Definitions" in the libcurl project


Note: The pre-processor settings can be found using the Visual Studio IDE
Note: The pre-processor settings can be found using the Visual Studio IDE
@@ -213,12 +213,12 @@ versions.
## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds
## Using BSD-style lwIP instead of Winsock TCP/IP stack in Win32 builds


In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is
In order to compile libcurl and curl using BSD-style lwIP TCP/IP stack it is
necessary to make definition of preprocessor symbol USE_LWIPSOCK visible to
necessary to make definition of preprocessor symbol `USE_LWIPSOCK` visible to
libcurl and curl compilation processes. To set this definition you have the
libcurl and curl compilation processes. To set this definition you have the
following alternatives:
following alternatives:


 - Modify lib/config-win32.h and src/config-win32.h
 - Modify `lib/config-win32.h` and `src/config-win32.h`
 - Modify winbuild/Makefile.vc
 - Modify `winbuild/Makefile.vc`
 - Modify the "Preprocessor Definitions" in the libcurl project
 - Modify the "Preprocessor Definitions" in the libcurl project


Note: The pre-processor settings can be found using the Visual Studio IDE
Note: The pre-processor settings can be found using the Visual Studio IDE
@@ -248,13 +248,13 @@ look for dynamic import symbols.


## Legacy Windows and SSL
## Legacy Windows and SSL


WinSSL (specifically Schannel from Windows SSPI), is the native SSL library in
Schannel (from Windows SSPI), is the native SSL library in Windows. However,
Windows. However, WinSSL in Windows <= XP is unable to connect to servers that
Schannel in Windows <= XP is unable to connect to servers that
no longer support the legacy handshakes and algorithms used by those
no longer support the legacy handshakes and algorithms used by those
versions. If you will be using curl in one of those earlier versions of
versions. If you will be using curl in one of those earlier versions of
Windows you should choose another SSL backend such as OpenSSL.
Windows you should choose another SSL backend such as OpenSSL.


# Apple iOS and Mac OS X
# Apple iOS and macOS


On modern Apple operating systems, curl can be built to use Apple's SSL/TLS
On modern Apple operating systems, curl can be built to use Apple's SSL/TLS
implementation, Secure Transport, instead of OpenSSL. To build with Secure
implementation, Secure Transport, instead of OpenSSL. To build with Secure
@@ -269,12 +269,12 @@ the server. This, of course, includes the root certificates that ship with the
OS. The `--cert` and `--engine` options, and their libcurl equivalents, are
OS. The `--cert` and `--engine` options, and their libcurl equivalents, are
currently unimplemented in curl with Secure Transport.
currently unimplemented in curl with Secure Transport.


For OS X users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul to
For macOS users: In OS X 10.8 ("Mountain Lion"), Apple made a major overhaul
the Secure Transport API that, among other things, added support for the newer
to the Secure Transport API that, among other things, added support for the
TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you must
newer TLS 1.1 and 1.2 protocols. To get curl to support TLS 1.1 and 1.2, you
build curl on Mountain Lion or later, or by using the equivalent SDK. If you
must build curl on Mountain Lion or later, or by using the equivalent SDK. If
set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier
you set the `MACOSX_DEPLOYMENT_TARGET` environmental variable to an earlier
version of OS X prior to building curl, then curl will use the new Secure
version of macOS prior to building curl, then curl will use the new Secure
Transport API on Mountain Lion and later, and fall back on the older API when
Transport API on Mountain Lion and later, and fall back on the older API when
the same curl binary is executed on older cats. For example, running these
the same curl binary is executed on older cats. For example, running these
commands in curl's directory in the shell will build the code such that it
commands in curl's directory in the shell will build the code such that it
@@ -288,7 +288,7 @@ will run on cats as old as OS X 10.6 ("Snow Leopard") (using bash):


Download and unpack the curl package.
Download and unpack the curl package.


'cd' to the new directory. (e.g. `cd curl-7.12.3`)
`cd` to the new directory. (e.g. `cd curl-7.12.3`)


Set environment variables to point to the cross-compile toolchain and call
Set environment variables to point to the cross-compile toolchain and call
configure with any options you need.  Be sure and specify the `--host` and
configure with any options you need.  Be sure and specify the `--host` and
@@ -327,7 +327,7 @@ In some cases, you may be able to simplify the above commands to as little as:


There are a number of configure options that can be used to reduce the size of
There are a number of configure options that can be used to reduce the size of
libcurl for embedded applications where binary size is an important factor.
libcurl for embedded applications where binary size is an important factor.
First, be sure to set the CFLAGS variable when configuring with any relevant
First, be sure to set the `CFLAGS` variable when configuring with any relevant
compiler optimization flags to reduce the size of the binary.  For gcc, this
compiler optimization flags to reduce the size of the binary.  For gcc, this
would mean at minimum the -Os option, and potentially the `-march=X`,
would mean at minimum the -Os option, and potentially the `-march=X`,
`-mdynamic-no-pic` and `-flto` options as well, e.g.
`-mdynamic-no-pic` and `-flto` options as well, e.g.
@@ -360,8 +360,8 @@ use, here are some other flags that can reduce the size of the library:


The GNU compiler and linker have a number of options that can reduce the
The GNU compiler and linker have a number of options that can reduce the
size of the libcurl dynamic libraries on some platforms even further.
size of the libcurl dynamic libraries on some platforms even further.
Specify them by providing appropriate CFLAGS and LDFLAGS variables on the
Specify them by providing appropriate `CFLAGS` and `LDFLAGS` variables on
configure command-line, e.g.
the configure command-line, e.g.


    CFLAGS="-Os -ffunction-sections -fdata-sections
    CFLAGS="-Os -ffunction-sections -fdata-sections
            -fno-unwind-tables -fno-asynchronous-unwind-tables -flto"
            -fno-unwind-tables -fno-asynchronous-unwind-tables -flto"
@@ -383,7 +383,7 @@ in a lower total size than dynamically linking.
Note that the curl test harness can detect the use of some, but not all, of
Note that the curl test harness can detect the use of some, but not all, of
the `--disable` statements suggested above. Use will cause tests relying on
the `--disable` statements suggested above. Use will cause tests relying on
those features to fail.  The test harness can be manually forced to skip the
those features to fail.  The test harness can be manually forced to skip the
relevant tests by specifying certain key words on the runtests.pl command
relevant tests by specifying certain key words on the `runtests.pl` command
line.  Following is a list of appropriate key words:
line.  Following is a list of appropriate key words:


 - `--disable-cookies`          !cookies
 - `--disable-cookies`          !cookies
+197 −191

File changed.

Preview size limit exceeded, changes collapsed.

+1 −1
Original line number Original line Diff line number Diff line
@@ -16,7 +16,7 @@ in the source code repo


- run "./maketgz 7.34.0" to build the release tarballs. It is important that
- run "./maketgz 7.34.0" to build the release tarballs. It is important that
  you run this on a machine with the correct set of autotools etc installed
  you run this on a machine with the correct set of autotools etc installed
  as this is what then will be shipped and used by most users on *nix like
  as this is what then will be shipped and used by most users on \*nix like
  systems.
  systems.


- push the git commits and the new tag
- push the git commits and the new tag
Loading