104 lines
4.5 KiB
ReStructuredText
104 lines
4.5 KiB
ReStructuredText
===================
|
|
README for PolarSSL
|
|
===================
|
|
|
|
Compiling
|
|
=========
|
|
|
|
There are currently three active build systems within the PolarSSL releases:
|
|
|
|
- Make
|
|
- CMake
|
|
- Microsoft Visual Studio (Visual Studio 6 and Visual Studio 2010)
|
|
|
|
The main system used for development is CMake. That system is always the most up-to-date. The others should reflect all changes present in the CMake build system, but some features are not ported there by default.
|
|
|
|
Make
|
|
----
|
|
|
|
We intentionally only use the absolute minimum of **Make** functionality, as we have discovered that a lot of **Make** features are not supported on all different implementations of Make on different platforms. As such, the Makefiles sometimes require some handwork or `export` statements in order to work for your platform.
|
|
|
|
In order to build the source using Make, just enter at the command line::
|
|
|
|
make
|
|
|
|
In order to run the tests, enter::
|
|
|
|
make check
|
|
|
|
Depending on your platform, you might run into some issues. Please check the Makefiles in *library/*, *programs/* and *tests/* for options to manually add or remove for specific platforms. You can also check `the PolarSSL Knowledge Base <https://polarssl.org/kb>`_ for articles on your platform or issue.
|
|
|
|
In case you find that you need to do something else as well, please let us know what, so we can add it to the KB.
|
|
|
|
CMake
|
|
-----
|
|
|
|
In order to build the source using CMake, just enter at the command line::
|
|
|
|
cmake .
|
|
|
|
make
|
|
|
|
There are 5 different active build modes specified within the CMake buildsystem:
|
|
|
|
- Release.
|
|
This generates the default code without any unnecessary information in the binary files.
|
|
- Debug.
|
|
This generates debug information and disables optimization of the code.
|
|
- Coverage.
|
|
This generates code coverage information in addition to debug information.
|
|
- ASan.
|
|
This instruments the code with AddressSanitizer to check for memory errors.
|
|
- Check.
|
|
This activates more compiler warnings and treats them as errors.
|
|
|
|
Switching build modes in CMake is simple. For debug mode, enter at the command line:
|
|
|
|
cmake -D CMAKE_BUILD_TYPE:String="Debug" .
|
|
|
|
In order to run the tests, enter::
|
|
|
|
make test
|
|
|
|
Microsoft Visual Studio
|
|
-----------------------
|
|
|
|
The build files for Microsoft Visual Studio are generated for Visual Studio 6.0 and Visual Studio 2010.
|
|
|
|
The workspace 'polarssl.dsw' contains all the basic projects needed to build the library and all the programs. The files in tests are not generated and compiled, as these need a perl environment as well.
|
|
|
|
Example programs
|
|
================
|
|
|
|
We've included example programs for a lot of different features and uses in *programs/*. Most programs only focus on a single feature or usage scenario, so keep that in mind when copying parts of the code.
|
|
|
|
Tests
|
|
=====
|
|
|
|
PolarSSL includes an elaborate test suite in *tests/* that initially requires Perl to generate the tests files (e.g. *test_suite_mpi.c*). These files are generates from a **function file** (e.g. *suites/test_suite_mpi.function*) and a **data file** (e.g. *suites/test_suite_mpi.data*). The **function file** contains the template for each test function. The **data file** contains the test cases, specified as parameters that should be pushed into a template function.
|
|
|
|
Configurations
|
|
==============
|
|
|
|
We provide some non-standard configurations focused on specific use cases in the configs/ directory. You can read more about those in configs/README.txt
|
|
|
|
Contributing
|
|
============
|
|
|
|
We graciously accept bugs and contributions from the community. There are some requirements we need to fulfil in order to be able to integrate contributions in the main code.
|
|
|
|
Simple bug fixes to existing code do not contain copyright themselves and we can integrate those without any issue. The same goes for trivial contributions.
|
|
|
|
For larger contributions, e.g. a new feature, the code possible falls under copyright law. We then need your consent to share in the ownership of the copyright. We have a form for that, which we will mail to you in case you submit a contribution or pull request that we deem this necessary for.
|
|
|
|
Process
|
|
-------
|
|
#. `Check for open issues <https://github.com/polarssl/polarssl/issues>`_ or
|
|
`start a discussion <https://polarssl.org/discussions>`_ around a feature
|
|
idea or a bug.
|
|
#. Fork the `PolarSSL repository on Github <https://github.com/polarssl/polarssl>`_
|
|
to start making your changes.
|
|
#. Write a test which shows that the bug was fixed or that the feature works
|
|
as expected.
|
|
#. Send a pull request and bug us until it gets merged and published. We will
|
|
include your name in the ChangeLog :)
|