diff --git a/README.md b/README.md index 5df7e57..6f03ea7 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,13 @@ Once you've made your great commits: 5. That's it! Disclaimer ------- +------------ The copyright holders are not liable for any damage(s) incurred due to improper use of sml. + +TODO +------------ +@todo Find a way to provide an option to clean installation. +@todo Find a way to remove \cond \endcond workaround to get Doxygen to not throw warnings in readme. +@todo Find a way to have nested variables in `Doxygen` config file so that e.g., `@@CMAKE_PROJECT_NAME@_VERSION@` works. +@todo Add version detection in `CMake` module so that find_package respects minimum version required. diff --git a/docs/README_8md.html b/docs/README_8md.html index 2095fa8..de93794 100644 --- a/docs/README_8md.html +++ b/docs/README_8md.html @@ -98,7 +98,7 @@
-Go to the documentation of this file.
1 sml
2 ===
3 
4 \cond [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) [![Build Status](https://travis-ci.org/openastro/sml.svg?branch=master)](https://travis-ci.org/openastro/sml) [![Coverity Scan Build Status](https://scan.coverity.com/projects/3666/badge.svg)](https://scan.coverity.com/projects/3666) [![Coverage Status](https://coveralls.io/repos/openastro/sml/badge.png)](https://coveralls.io/r/openastro/sml) \endcond
5 
6 SML (Simple Mathematics Library) is a C++ (template) library that provides basic mathematics functionality. The library is intended to be lightweight and simple to use in other projects. A CMake module is available to make it easy to include SML in other CMake-based projects: [Findsml.cmake](https://github.com/openastro/cmake-modules/blob/master/Modules/Findsml.cmake).
7 
8 Features
9 ------
10 
11  - Header-only
12  - Generic linear algebra functions
13  - Basic constants
14  - Full suite of tests
15 
16 Requirements
17 ------
18 
19 To install this project, please ensure that you have installed the following (install guides are provided on the respective websites):
20 
21  - [Git](http://git-scm.com)
22  - A C++ compiler, e.g., [GCC](https://gcc.gnu.org/), [clang](http://clang.llvm.org/), [MinGW](http://www.mingw.org/)
23  - [CMake](http://www.cmake.org "CMake homepage")
24  - [Doxygen](http://www.doxygen.org "Doxygen homepage") (optional)
25  - [Gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) (optional)
26  - [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) (optional)
27 
28 The following dependencies are optional (see `Build options`):
29 
30  - [CATCH](https://www.github.com/philsquared/Catch) (unit testing library necessary for `BUILD_TESTS` build option)
31 
32 These dependencies will be downloaded and configured automagically if not already present locally (requires an internet connection).
33 
34 Installation
35 ------
36 
37 Run the following commands to download, build, and install this project.
38 
39  git clone https://www.github.com/openastro/sml
40  cd sml
41  git submodule init && git submodule update
42  mkdir build && cd build
43  cmake .. && cmake --build .
44 
45 To install the header files, run the following from within the `build` directory:
46 
47  make install
48 
49 Note that dependencies are installed by fetching them online, in case they cannot be detected on your local system. If the build process fails, check the error log given. Typically, building fails due to timeout. Simply run the `cmake --build .` command once more.
50 
51 Build options
52 -------------
53 
54 You can pass the following, general command-line options when running CMake:
55 
56  - `-DCMAKE_INSTALL_PREFIX[=$install_dir]`: set path prefix for install script (`make install`); if not set, defaults to usual locations
57  - `-DBUILD_DOXYGEN_DOCS[=ON|OFF (default)]`: build the [Doxygen](http://www.doxygen.org "Doxygen homepage") documentation ([LaTeX](http://www.latex-project.org/) must be installed with `amsmath` package)
58  - `-DBUILD_TESTS[=ON|OFF (default)]`: build tests (execute tests from build-directory using `ctest -V`)
59  - `-DBUILD_DEPENDENCIES[=ON|OFF (default)]`: force local build of dependencies, instead of first searching system-wide using `find_package()`
60 
61 The following commands are conditional and can only be set if `BUILD_TESTS = ON`:
62 
63  - `-DBUILD_COVERAGE_ANALYSIS[=ON|OFF (default)]`: build code coverage using [Gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) and [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) (both must be installed; requires [GCC](https://gcc.gnu.org/) compiler; execute coverage analysis from build-directory using `make coverage`)
64 
65 Pass these options either directly to the `cmake ..` command, e.g., to build the tests:
66 
67  cmake -DBUILD_TESTS=on ..
68 
69 N.B.: Toggling options to build tests using `ccmake` does not work correctly, as the necessarily libraries are not download automagically!
70 
71 Project structure
72 -------------
73 
74 This project has been set up with a specific file/folder structure in mind. The following describes some important features of this setup:
75 
76  - `cmake/Modules` : Contains `CMake` modules, including `Findsml.cmake` module
77  - `docs`: Contains project-specific docs in [Markdown](https://help.github.com/articles/github-flavored-markdown/ "GitHub Flavored Markdown") that are also parsed by [Doxygen](http://www.doxygen.org "Doxygen homepage"). This sub-directory includes `global_todo.md`, which contains a global list of TODO items for project that appear on TODO list generated in [Doxygen](http://www.doxygen.org "Doxygen homepage") documentation
78  - `doxydocs`: HTML output generated by building [Doxygen](http://www.doxygen.org "Doxygen homepage") documentation
79  - `include/sml`: Project header files (*.hpp)
80  - `scripts`: Shell scripts used in [Travis CI](https://travis-ci.org/ "Travis CI homepage") build
81  - `test`: Project test source files (*.cpp) that are provided to the [Catch](https://www.github.com/philsquared/Catch "Catch Github repository") framework
82  - `.travis.yml`: Configuration file for [Travis CI](https://travis-ci.org/ "Travis CI homepage") build, including static analysis using [Coverity Scan](https://scan.coverity.com/ "Coverity Scan homepage") and code coverage using [Coveralls](https://coveralls.io "Coveralls.io homepage")
83  - `CMakeLists.txt`: main `CMakelists.txt` file for project (should not need to be modified for basic build)
84  - `Dependencies.cmake`: list of dependencies and automated build, triggered if dependency cannot be found locally
85  - `Doxyfile.in`: [Doxygen](http://www.doxygen.org "Doxygen homepage") configuration file, adapted for generic use within project build (should not need to be modified)
86  - `LICENSE.md`: license file for project (copyright statement needs to be edited)
87  - `ProjectFiles.cmake`: list of project source files to build
88  - `README.md`: project readme file, parsed as main page for [Doxygen](http://www.doxygen.org "Doxygen homepage") documentation
89 
90 Contributing
91 ------------
92 
93 Once you've made your great commits:
94 
95  1. [Fork](https://github.com/openastro/sml/fork) sml
96  2. Create a topic branch - `git checkout -b my_branch`
97  3. Push to your branch - `git push origin my_branch`
98  4. Create a [Pull Request](http://help.github.com/pull-requests/) from your branch
99  5. That's it!
100 
101 Disclaimer
102 ------
103 
104 The copyright holders are not liable for any damage(s) incurred due to improper use of sml.
+Go to the documentation of this file.
1 sml
2 ===
3 
4 \cond [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) [![Build Status](https://travis-ci.org/kartikkumar/sml.svg?branch=master)](https://travis-ci.org/kartikkumar/sml) [![Coverity Scan Build Status](https://scan.coverity.com/projects/3666/badge.svg)](https://scan.coverity.com/projects/3666) [![Coverage Status](https://coveralls.io/repos/github/kartikkumar/sml/badge.svg?branch=master)](https://coveralls.io/github/kartikkumar/sml?branch=master) \endcond
5 
6 sml (simple mathematics library) is a C++ (template) library that provides basic mathematics functionality. The library is intended to be lightweight and simple to use in other projects. A CMake module is available to make it easy to include sml in other CMake-based projects: [Findsml.cmake](https://github.com/openastro/cmake-modules/blob/master/Modules/Findsml.cmake).
7 
8 Features
9 ------
10 
11  - Header-only, zero-dependency
12  - Generic linear algebra functions
13  - Basic constants
14  - Full suite of tests
15 
16 Requirements
17 ------
18 
19 To install this project, please ensure that you have installed the following (install guides are provided on the respective websites):
20 
21  - [Git](http://git-scm.com)
22  - A C++ compiler, e.g., [GCC](https://gcc.gnu.org/), [clang](http://clang.llvm.org/), [MinGW](http://www.mingw.org/)
23  - [CMake](http://www.cmake.org "CMake homepage")
24  - [Doxygen](http://www.doxygen.org "Doxygen homepage") (optional)
25  - [Gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) (optional)
26  - [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) (optional)
27 
28 The following dependencies are optional (see `Build options`):
29 
30  - [Catch2](https://github.com/catchorg/Catch2) (unit testing library necessary for `BUILD_TESTS` build option)
31 
32 These dependencies will be downloaded and configured automagically if not already present locally (requires an internet connection).
33 
34 Installation
35 ------
36 
37 Run the following commands to download, build, and install this project.
38 
39  git clone https://www.github.com/openastro/sml
40  cd sml
41  git submodule init && git submodule update
42  mkdir build && cd build
43  cmake .. && cmake --build .
44 
45 To install the header files, run the following from within the `build` directory:
46 
47  make install
48 
49 Note that dependencies are installed by fetching them online, in case they cannot be detected on your local system. If the build process fails, check the error log given. Typically, building fails due to timeout. Simply run the `cmake --build .` command once more.
50 
51 Build options
52 -------------
53 
54 You can pass the following, general command-line options when running CMake:
55 
56  - `-DCMAKE_INSTALL_PREFIX[=$install_dir]`: set path prefix for install script (`make install`); if not set, defaults to usual locations
57  - `-DBUILD_DOXYGEN_DOCS[=ON|OFF (default)]`: build the [Doxygen](http://www.doxygen.org "Doxygen homepage") documentation ([LaTeX](http://www.latex-project.org/) must be installed with `amsmath` package)
58  - `-DBUILD_TESTS[=ON|OFF (default)]`: build tests (execute tests from build-directory using `ctest -V`)
59  - `-DBUILD_DEPENDENCIES[=ON|OFF (default)]`: force local build of dependencies, instead of first searching system-wide using `find_package()`
60 
61 The following commands are conditional and can only be set if `BUILD_TESTS = ON`:
62 
63  - `-DBUILD_COVERAGE_ANALYSIS[=ON|OFF (default)]`: build code coverage using [Gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) and [LCOV](http://ltp.sourceforge.net/coverage/lcov.php) (both must be installed; requires [GCC](https://gcc.gnu.org/) compiler; execute coverage analysis from build-directory using `make coverage`)
64 
65 Pass these options either directly to the `cmake ..` command, e.g., to build the tests:
66 
67  cmake -DBUILD_TESTS=on ..
68 
69 N.B.: Toggling options to build tests using `ccmake` does not work correctly, as the necessarily libraries are not download automagically!
70 
71 Project structure
72 -------------
73 
74 This project has been set up with a specific file/folder structure in mind. The following describes some important features of this setup:
75 
76  - `cmake/Modules` : Contains `CMake` modules, including `Findsml.cmake` module
77  - `docs`: Contains code documentation generated by [Doxygen](http://www.doxygen.org "Doxygen homepage")
78  - `include/sml`: Project header files (*.hpp)
79  - `scripts`: Shell scripts used in [Travis CI](https://travis-ci.org/ "Travis CI homepage") build
80  - `test`: Project test source files (*.cpp) that are provided to the [Catch2](https://github.com/catchorg/Catch2 "Catch2 Github repository") framework
81  - `.travis.yml`: Configuration file for [Travis CI](https://travis-ci.org/ "Travis CI homepage") build, including static analysis using [Coverity Scan](https://scan.coverity.com/ "Coverity Scan homepage") and code coverage using [Coveralls](https://coveralls.io "Coveralls.io homepage")
82  - `CMakeLists.txt`: main `CMakelists.txt` file for project (should not need to be modified for basic build)
83  - `Dependencies.cmake`: list of dependencies and automated build, triggered if dependency cannot be found locally
84  - `Doxyfile.in`: [Doxygen](http://www.doxygen.org "Doxygen homepage") configuration file, adapted for generic use within project build (should not need to be modified)
85  - `LICENSE.md`: license file for project (copyright statement needs to be edited)
86  - `ProjectFiles.cmake`: list of project source files to build
87  - `README.md`: project readme file, parsed as main page for [Doxygen](http://www.doxygen.org "Doxygen homepage") documentation
88 
89 Contributing
90 ------------
91 
92 Once you've made your great commits:
93 
94  1. [Fork](https://github.com/openastro/sml/fork) sml
95  2. Create a topic branch - `git checkout -b my_branch`
96  3. Push to your branch - `git push origin my_branch`
97  4. Create a [Pull Request](http://help.github.com/pull-requests/) from your branch
98  5. That's it!
99 
100 Disclaimer
101 ------------
102 
103 The copyright holders are not liable for any damage(s) incurred due to improper use of sml.
104 
105 TODO
106 ------------
107 @todo Find a way to provide an option to clean installation.
108 @todo Find a way to remove \cond \endcond workaround to get Doxygen to not throw warnings in readme.
109 @todo Find a way to have nested variables in `Doxygen` config file so that e.g., `@@CMAKE_PROJECT_NAME@_VERSION@` works.
110 @todo Add version detection in `CMake` module so that find_package respects minimum version required.