blob: 95b7ee122a801c7b870a3e272c6441530f468812 [file] [log] [blame] [view]
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07001Notes for ndn-cxx developers
2============================
3
Nick Gordonfe13f562017-12-21 14:12:37 -06004If you are new to the NDN community of software generally, read the
Davide Pesavento78338c52020-04-20 23:00:02 -04005[Contributor's Guide](https://github.com/named-data/.github/blob/master/CONTRIBUTING.md).
Nick Gordonfe13f562017-12-21 14:12:37 -06006
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -07007Code style
8----------
9
Davide Pesavento46b04a52019-03-28 21:36:35 -040010ndn-cxx code is subject to [ndn-cxx code style](https://named-data.net/doc/ndn-cxx/current/code-style.html).
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070011
12Licensing
13---------
14
Davide Pesavento46b04a52019-03-28 21:36:35 -040015Contributions to the library must be licensed under the LGPL v3 or compatible license. If
16you are choosing LGPL v3, please use the following license boilerplate in all `.hpp` and
Alexander Afanasyevc169a812014-05-20 20:37:29 -040017`.cpp` files:
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070018
Alexander Afanasyevc169a812014-05-20 20:37:29 -040019 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
Junxiao Shibd2cedb2017-07-05 18:51:52 +000020 /*
Davide Pesavento46b04a52019-03-28 21:36:35 -040021 * Copyright (c) [Year(s)] [Copyright Holder(s)].
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070022 *
23 * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070024 *
Alexander Afanasyevc169a812014-05-20 20:37:29 -040025 * ndn-cxx library is free software: you can redistribute it and/or modify it under the
26 * terms of the GNU Lesser General Public License as published by the Free Software
27 * Foundation, either version 3 of the License, or (at your option) any later version.
28 *
29 * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
30 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
31 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
32 *
33 * You should have received copies of the GNU General Public License and GNU Lesser
34 * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
35 * <http://www.gnu.org/licenses/>.
36 *
37 * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
Alexander Afanasyevdfa52c42014-04-24 21:10:11 -070038 ////// [optional part] //////
39 *
40 * @author Author's Name <email@domain-or-homepage://url>
41 * @author Other Author's Name <another.email@domain-or-homepage://url>
42 ////// [end of optional part] //////
43 */
Alexander Afanasyevaf99f462015-01-19 21:43:09 -080044
45If you are affiliated to an NSF-supported NDN project institution, please use the [NDN Team License
Davide Pesavento0530b5b2016-11-07 03:23:58 +010046Boilerplate](https://redmine.named-data.net/projects/ndn-cxx/wiki/NDN_Team_License_Boilerplate_(ndn-cxx)).
Alexander Afanasyevcf490552016-06-27 22:51:36 -070047
Davide Pesavento74daf742018-11-23 18:14:13 -050048Running unit tests
Alexander Afanasyevcf490552016-06-27 22:51:36 -070049------------------
50
Davide Pesavento534b8412018-12-08 19:19:09 -050051To run the unit tests, ndn-cxx needs to be built with unit test support and installed
Alexander Afanasyevcf490552016-06-27 22:51:36 -070052into the configured location. For example:
53
Davide Pesavento46b04a52019-03-28 21:36:35 -040054 ./waf configure --with-tests # --debug is also strongly recommended while developing
Alexander Afanasyevcf490552016-06-27 22:51:36 -070055 ./waf
56 sudo ./waf install
57
Davide Pesavento534b8412018-12-08 19:19:09 -050058**Note**: On Linux you also need to run `sudo ldconfig` to reconfigure dynamic loader
59run-time bindings.
Alexander Afanasyevcf490552016-06-27 22:51:36 -070060
Davide Pesavento534b8412018-12-08 19:19:09 -050061The simplest way to run the tests is to launch the compiled binary without any parameters:
Alexander Afanasyevcf490552016-06-27 22:51:36 -070062
63 ./build/unit-tests
64
Davide Pesavento78338c52020-04-20 23:00:02 -040065The [Boost.Test framework](https://www.boost.org/doc/libs/1_65_1/libs/test/doc/html/index.html)
Alexander Afanasyevcf490552016-06-27 22:51:36 -070066is very flexible and allows a number of run-time customization of what tests should be run.
67For example, it is possible to choose to run only a specific test suite, only a specific
68test case within a suite, or specific test cases within specific test suites:
69
Davide Pesavento74daf742018-11-23 18:14:13 -050070 # Run only Face test suite tests (tests/unit/face.t.cpp)
Alexander Afanasyevcf490552016-06-27 22:51:36 -070071 ./build/unit-tests -t TestFace
72
73 # Run only test case ExpressInterestData from the same test suite
74 ./build/unit-tests -t TestFace/ExpressInterestData
75
76 # Run Basic test case from all test suites
77 ./build/unit-tests -t */Basic
78
79By default, Boost.Test framework will produce verbose output only when a test case fails.
80If it is desired to see verbose output (result of each test assertion), add `-l all`
Davide Pesavento534b8412018-12-08 19:19:09 -050081option to `./build/unit-tests` command. To see test progress, you can use `-l test_suite`,
82or `-p` to show a progress bar:
Alexander Afanasyevcf490552016-06-27 22:51:36 -070083
84 # Show report all log messages including the passed test notification
85 ./build/unit-tests -l all
86
87 # Show test suite messages
88 ./build/unit-tests -l test_suite
89
90 # Show nothing
91 ./build/unit-tests -l nothing
92
93 # Show progress bar
94 ./build/unit-tests -p
95
96There are many more command line options available, information about which can be obtained
Davide Pesavento78338c52020-04-20 23:00:02 -040097either from the command line using the `--help` switch, or online on the
98[Boost.Test website](https://www.boost.org/doc/libs/1_65_1/libs/test/doc/html/index.html).
Alexander Afanasyevcf490552016-06-27 22:51:36 -070099
100**Warning:** If you have customized parameters for NDN platform using `client.conf` in
101`/etc/ndn` or `/usr/local/etc/ndn` (or other `@SYSCONFDIR@/etc` if it was configured to custom
102path during `./waf configure`), Face-related test cases may fail.