1.. _testing_ctags: 2 3============================================================================= 4Testing ctags 5============================================================================= 6 7.. contents:: `Table of contents` 8 :depth: 1 9 :local: 10 11.. tmain.rst 12 13*Tmain*: a facility for testing main part 14------------------------------------------------------------ 15 16:Maintainer: Masatake YAMATO <yamato@redhat.com> 17 18---- 19 20*Tmain* is introduced to test the area where *Units* 21does not cover well. 22 23*Units* works fine for testing parsers. However, it 24assumes something input is given to ctags command, 25and a `tags` file is generated from ctags command. 26 27Other aspects cannot be tested. Such areas are files 28and directories layout after installation, standard 29error output, exit status, etc. 30 31You can run test cases with following command line: 32 33:: 34 35 $ make tmain 36 37*Tmain* is still under development so I will not write 38the details here. 39 40 41To write a test case, see files under `Tmain/tmain-example.d`. 42In the example, *Tmain* does: 43 441. runs new subshell and change the working directory to `Tmain/tmain-example.d`, 452. runs `run.sh` with `bash`, 463. captures stdout, stderr and exit status, and 474. compares them with `stdout-expected.txt`, `stderr-expected.txt`, 48 and `exit-expected.txt`. 495. compares it with `tags-expected.txt` if run.sh generates `tags` file. 50 51`run.sh` is run with following 3 arguments: 52 531. the path for the target ctags 542. the path for `builddir` directory 553. the path for the target readtags 56 57The path for readtags is not reliable; readtags command is not 58available if --disable-readcmd was given in configure time. A case, 59testing the behavior of readtags, must verify the command existence 60with `test -x $3` before going into the main part of the test. 61 62When comparing `tags` file with `tags-expected.txt`, you 63must specify the path of `tags` explicitly with -o option 64in ctags command line like:: 65 66 CTAGS=$1 67 BUILDDIR=$2 68 ${CTAGS} ... -o $BUILDDIR/tags ... 69 70This makes it possible to keep the original source directory clean. 71 72See also `tmain_run` and `tmain_compare` functions in `misc/units`. 73 74If run.sh exits with code 77, the test case is skipped. 75The output to stdout is captured and printed as the reason 76of skipping. 77 78TODO 79~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 80 81* Run under valgrind 82 83.. tinst.rst 84 85*Tinst*: installation test 86--------------------------------------------------------------------- 87 88:Maintainer: Masatake YAMATO <yamato@redhat.com> 89 90----- 91 92tinst target is for testing the result of ``make install``. 93 94:: 95 96 $ make tinst 97 98Fussy syntax checking 99------------------------------------------------------------ 100If ``-Wall`` of gcc is not enough, you may be interested in this. 101 102You can change C compiler warning options with 'WARNING_CFLAGS' 103configure arg-var option. 104 105:: 106 107 $ ./configure WARNING_CFLAGS='-Wall -Wextra' 108 109 110If configure option '--with-sparse-cgcc' is specified, 111cgcc is used as CC. cgcc is part of `Sparse, Semantic Parser for C 112<https://sparse.docs.kernel.org/en/latest/>`_. 113It is used in development of Linux kernel for finding programming error. 114cgcc acts as a c compiler but more fussy. '-Wsparse-all' is used as 115default option passed to cgcc but you can change with 'CGCC_CFLAGS' 116configure arg-var option. 117 118:: 119 120 $ ./configure --with-sparse-cgcc [CGCC_CFLAGS='-Wsparse-all'] 121 122 123Finding performance bottleneck 124------------------------------------------------------------ 125 126See `Profiling with gperftools 127<https://wiki.geany.org/howtos/profiling/gperftools>`_ and `#383 128<https://github.com/universal-ctags/ctags/issues/383>`_. 129 130See also `codebase <https://github.com/universal-ctags/codebase>`_. 131 132Checking coverage 133------------------------------------------------------------ 134Before starting coverage measuring, you need to specify 135'--enable-coverage-gcov' configure option. 136 137:: 138 139 $ ./configure --enable-coverage-gcov 140 141 142After doing ``make clean``, you can build coverage measuring ready 143ctags by ``make``. At this time *\*.gcno* files are generated 144by the compiler. *\*.gcno* files can be removed with ``make clean``. 145 146After building ctags, you can run run-gcov target. When running 147*\*.gcda* files. The target runs ctags with all input files under 148*Units/\*\*/input.\**; and call ``gcov``. Human readable result is 149printed. The detail can be shown in *\*.gcov*. files. *\*.gcda* files 150and *\*.gcov* files can be removed with ``make clean-gcov``. 151 152Running cppcheck 153------------------------------------------------------------ 154 155.. NOT REVIEWED YET 156 157`cppcheck <http://cppcheck.sourceforge.net/>`_ is a tool for static C/C++ code 158analysis. 159 160To run it do as following after install cppcheck:: 161 162 $ make cppcheck 163