Differences from BoringSSL and OpenSSL
======================================

Here are the major differences between *ring* and BoringSSL & OpenSSL that
affect building:

* BoringSSL uses CMake and OpenSSL uses make(1). *ring* uses Visual Studio's
  native build system (msbuild) on Windows, and GNU Make otherwise.
* BoringSSL and OpenSSL both support building static or shared libraries.
  *ring* is only supported in static library form.
* *ring*'s static library is named ring.lib on Windows and libring.a on
  other platforms. BoringSSL and OpenSSL use different names.



Building on Linux and Similar Platforms
=======================================

There is no ./configure step.

GNU Make 3.81 or later is required. Perl 5.6.1 or later is also required
(unless you disable all the assembly language optimizations by building
with ```NO_ASM=1```). *ring* is designed with cross-compilation in mind so it
expects variables ```CC```, ```CXX```, and ```TARGET``` to be passed
to ```make```. For example, this will build a 32-bit x86 *ring* for Linux using
GCC 4.8:

    make -j6 CC=gcc-4.8 CXX=g++-4.8 TARGET=i586-pc-linux-gnu

You must include all four parts in ```TARGET```, except on Mac OS X you can
omit the ABI. For example, this will build a 64-bit x86-64 *ring* for Mac OS X:

    make -j6 CC=clang CXX=clang++ TARGET=x86_64-apple-darwin

All four parts of the target are required.

GCC 4.8 and later are supported, as are clang 3.4 and later. Other compilers
will also probably work without too much trouble. Note in particular that if
you are cross-compiling an x86 build on a 64-bit version of Linux, then you
need to have the proper gcc-multilibs and g++-multilibs packages or equivalent
installed.

The default build is a release build (```CMAKE_BUILD_TYPE=RELWITHDEBINFO```).
You can build a debug build by setting ```CMAKE_BUILD_TYPE``` to ```DEBUG```.
(Note that the variable is named to be consistent with CMake, but CMake is not
used.) For example, this will build *ring* in release mode with the default
version of clang on Mac OS X:

    make -j6 CC=clang-3.6 CXX=clang++-3.6 TARGET=x86_64-pc-linux-gnu CMAKE_BUILD_TYPE=DEBUG

Then compile your applications with ```-Iring/include``` (assuming you put *ring*
into the ```ring``` subdirectory of your project) and add ```$(RING_LDFLAGS)```
to LDFLAGS in your linking step. ```RING_LDFLAGS``` expands by default
to ```-pthread -Lbuild/$TARGET-$CC/lib -lring```. (It should also be
easy to build *ring* so that it doesn't depend on pthreads, but the build system
hasn't been enhanced to fully support that yet.)

Running the tests using ```make check``` requires Go (https://golang.org/) to
be in ```$PATH```. Example:

    make check -j6 CC=clang-3.6 CXX=clang++-3.6 TARGET=x86_64-pc-linux-gnu



Building on Windows
===================

Note that currently the assembly language optimizations are NOT built on
Windows yet, only because the additions to the project files to support doing
so haven't been made yet.

The Windows build requires Visual Studio 2013 or later. Any edition will work.
Open ```ring.sln``` in Visual Studio and choose Build|Build Solution.
Alternatively, from a Visual Studio Native Tools Command Prompt:

    msbuild ring.sln

The built ```ring.lib``` will be put into a subdirectory of ```build/``` depending
on which configuration and which platform you choose to build for. For example,
in a 32-bit release build, the result is ```build\Win32-Release\lib\ring.lib```.
In your application's project, add *ring*'s ```include/``` subdirectory to the
"Additional Include Directories," add the directory containing ```ring.lib```
to the "Additional Library Directories", and add ```ring.lib``` to the
"Additional Dependencies."

On Windows, *ring* can be build in Debug or Release configurations for
platforms Win32 or x64. (It should be easy to add support for the ARM platform
too.) The solution builds correctly using either Visual Studio 2013 or Visual
Studio 2015 without any conversion steps being necessary. The project files are
mostly hand-written and rely heavily on the property sheets in ```mk\*.props```.
All Visual Studio features should work. However, Visual Studio's project property
editor often wrongly shows properties set in the property sheets as being
unset. In general, it is much better to edit the ```*.props``` files by hand
instead of using Visual Studio's GUI to edit the projects.

The tests currently require Go (https://golang.org/). For a 64-bit release
build, run this from within the *ring* subdirectory:

    go run util/all_tests.go --build-dir=build/x64-Release/test/ring