-As of version 0.1, BearSSL is a simple static library. Most of the
-process is rather manual and old-style, and there is no installer (this
-will be added in a later version, in particular when all the man pages
-for BearSSL functions are written).
-
- 1. Have a look at the top of the `Makefile`. There you can configure the
- command names and flags for invoking the C compiler, linker, and
- static library archiver.
-
- 2. There are a few configurable switches in `src/config.h`. These switches
- relate to compile-time options, e.g. support of a system-provided
- random source. On usual platforms (e.g. Linux or OS X), auto-detection
- should work, but you can always override things with `config.h`.
-
- 3. Type `make`. This should produce the static library (`libbearssl.a`),
- the test executables (`testcrypto`, `testspeed` and `testx509`), and
- the command-line debug tool (`brssl`). You might want to run the tests:
-
- - `testcrypto all` runs the cryptographic tests (test vectors on all
- implemented cryptogaphic functions). It can be slow.
-
- - `testspeed all` runs a number of performance benchmarks, there again
- on cryptographic functions. It gives a taste of how things go on the
- current platform.
-
- - `testx509` runs X.509 validation tests. The test certificates are
- all in `test/x509/`.
-
- 4. The `brssl` command-line tool is a stand-alone binary. It can exercise
- some of the functionalities of BearSSL, in particular running a test
- SSL client or server. It is not meant for production purposes (e.g.
- the SSL client has a mode where it disregards the inability to validate
- the server's certificate, which is inherently unsafe, but convenient
- for debug).
-
- 5. Using the library means writing some application code that invokes it,
- and linking with the static library. The header files are all in the
- `inc` directory; copy them wherever makes sense (e.g. in the
- `/usr/local/include` directory). The library itself (`libbearssl.a`)
- is what you link against.
-
- Alternatively, you may want to copy the source files directly into
- your own application code. This will make integrating ulterior versions
- of BearSSL more difficult. If you still want to go down that road,
- then simply copy all the `*.h` and `*.c` files from the `src` and `inc`
- directories into your application source code. In the BearSSL source
- archive, the source files are segregated into various sub-directories,
- but this is for my convenience only. There is no technical requirement
- for that, and all files can be dumped together in a simple directory.
-
- Dependencies are simple and systematic:
-
- - Each `*.c` file includes `inner.h`
- - `inner.h` includes `config.h` and `bearssl.h`
- - `bearssl.h` includes the other `bearssl_*.h`
+Right now, BearSSL is a simple library, along with a few test and debug
+command-line tools. There is no installer yet. The library _can_ be
+compiled as a shared library on some systems, but since the binary API
+is not fully stabilised, this is not a very good idea to do that right
+now.
+
+To compile the code, just type `make`. This will try to use sane
+"default" values. On a Windows system with Visual Studio, run a console
+with the environment initialised for a specific version of the C compiler,
+and type `nmake`.
+
+To override the default settings, create a custom configuration file in
+the `conf` directory, and invoke `make` (or `nmake`) with an explicit
+`CONF=` parameter. For instance, to use the provided `samd20.mk`
+configuration file (that targets cross-compilation for an Atmel board
+that features a Cortex-M0+ CPU), type:
+
+ make CONF=samd20
+
+The `conf/samd20.mk` file includes the `Unix.mk` file and then overrides
+some of the parameters, including the destination directory. Any custom
+configuration can be made the same way.
+
+Some compile-time options can be set through macros, either on the
+compiler command-line, or in the `src/config.h` file. See the comments
+in that file. Some settings are autodetected but they can still be
+explicitly overridden.
+
+When compilation is done, the library (static and DLL, when appropriate)
+and the command-line tools can be found in the designated build
+directory (by default named `build`). The public headers (to be used
+by applications linked against BearSSL) are in the `inc/` directory.
+
+To run the tests:
+
+ - `testcrypto all` runs the cryptographic tests (test vectors on all
+ implemented cryptogaphic functions). It can be slow. You can also
+ run a selection of the tests by providing their names (run
+ `testcrypto` without any parameter to see the available names).
+
+ - `testspeed all` runs a number of performance benchmarks, there again
+ on cryptographic functions. It gives a taste of how things go on the
+ current platform. As for `testcrypto`, specific named benchmarks can
+ be executed.
+
+ - `testx509` runs X.509 validation tests. The test certificates are
+ all in `test/x509/`.
+
+The `brssl` command-line tool produced in the build directory is a
+stand-alone binary. It can exercise some of the functionalities of
+BearSSL, in particular running a test SSL client or server. It is not
+meant for production purposes (e.g. the SSL client has a mode where it
+disregards the inability to validate the server's certificate, which is
+inherently unsafe, but convenient for debug).
+
+**Using the library** means writing some application code that invokes
+it, and linking with the static library. The header files are all in the
+`inc` directory; copy them wherever makes sense (e.g. in the
+`/usr/local/include` directory). The library itself (`libbearssl.a`) is
+what you link against.
+
+Alternatively, you may want to copy the source files directly into your
+own application code. This will make integrating ulterior versions of
+BearSSL more difficult. If you still want to go down that road, then
+simply copy all the `*.h` and `*.c` files from the `src` and `inc`
+directories into your application source code. In the BearSSL source
+archive, the source files are segregated into various sub-directories,
+but this is for my convenience only. There is no technical requirement
+for that, and all files can be dumped together in a simple directory.
+
+Dependencies are simple and systematic:
+
+ - Each `*.c` file includes `inner.h`
+ - `inner.h` includes `config.h` and `bearssl.h`
+ - `bearssl.h` includes the other `bearssl_*.h`