From 09b9554c30fccffd56cd9e0239415e5f7f597790 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Fri, 2 Dec 2011 13:45:08 +1030 Subject: [PATCH] doc: man page for ccanlint. --- doc/Makefile | 5 + doc/ccanlint.1 | 455 +++++++++++++++++++++++++++++++++++++++++++++ doc/ccanlint.1.txt | 267 ++++++++++++++++++++++++++ 3 files changed, 727 insertions(+) create mode 100644 doc/Makefile create mode 100644 doc/ccanlint.1 create mode 100644 doc/ccanlint.1.txt diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..57307923 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,5 @@ +ccanlint.1: ccanlint.1.txt + a2x --format=manpage ccanlint.1.txt + +distclean: + rm -f ccanlint.1 diff --git a/doc/ccanlint.1 b/doc/ccanlint.1 new file mode 100644 index 00000000..4febdc38 --- /dev/null +++ b/doc/ccanlint.1 @@ -0,0 +1,455 @@ +'\" t +.\" Title: ccanlint +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.75.2 +.\" Date: 12/02/2011 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CCANLINT" "1" "12/02/2011" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ccanlint \- Make CCAN code modules, and the brightness up\&. +.SH "SYNOPSIS" +.sp +\fBccanlint\fR [\fIOPTIONS\fR] [\fIDIRECTORY\fR\&...] +.SH "DESCRIPTION" +.sp +No encoder? No need to \fBccanlint\fR\&. You programmer? Excited to \fBccanlint\fR! +.sp +CCAN module is small code of the song\&. \fBccanlint\fR full CCAN testing tool\&. Each test spray bit of wisdom\&. Also score\&. Good score good\&. Bad bad score\&. +.sp +\fBccanlint\fR expect the source code in this directory, or command line can be more than one\&. Exit 0 happy if all modules all tests happy\&. +.SH "OPTIONS" +.PP +\fB\-v, \-\-verbose\fR +.RS 4 +Make +\fBccanlint\fR +talkative\&. "\-vv" doing very talkative\&. "\-vvvv" make stupid talker\&. +.RE +.PP +\fB\-n, \-\-safe\-mode\fR +.RS 4 +Do not compile anything\&. Could it be safer for the bad code, but +\fBccanlint\fR +sad useless\&. +.RE +.PP +\fB\-l, \-\-list\-tests\fR +.RS 4 +Tests show +\fBccanlint\fR +can do\&. Then die happy\&. +.RE +.PP +\fB\-\-test\-dep\-graph\fR +.RS 4 +Chart of all parties +\fBccanlint\fR +tests +\fIdot(1)\fR +Graphviz, then die happy\&. +.RE +.PP +\fB\-k, \-\-keep\fR +.RS 4 + +\fBccanlint\fR +normally make mess temporary directory, but now it later in forensic\&. +.RE +.PP +\fB\-s, \-\-summary\fR +.RS 4 + +\fBccanlint\fR +just realized there is no message unless you die horrible\&. +.RE +.PP +\fB\-x, \-\-exclude\fR=\fITESTNAME\fR +.RS 4 +No test run\&. Can the use of time many, many do +\fBccanlint\fR +very, very quickly\&. Often hatred +\fItests_run_valgrind\fR +that the test slowed\&. +.RE +.PP +\fB\-\-timeout\fR=\fIMILLISECONDS\fR +.RS 4 +Stop the test and forget it if you take too long\&. Generally, the same works as +\fI\-x tests_run_valgrind\fR\&. +.RE +.PP +\fB\-t, \-\-target\fR=\fITESTNAME\fR +.RS 4 +Do not run all tests\&. Run this test, and the proof you need\&. Used many times for many tests\&. +.RE +.PP +\fB\-\-compiler\fR=\fICOMPILER\fR +.RS 4 + +\fBccanlint\fR +read config\&.h about finding +\fICCAN_COMPILER\fR\&. Otherwise use the default when it was built\&. The change, to use this compiler\&. +.RE +.PP +\fB\-\-cflags\fR=\fICFLAGS\fR +.RS 4 +Set compiler options to compile\&. Be sure to protect spaces shell hunger\&. +.RE +.SH "TESTS" +.sp +\fBccanlint\fR many tests\&. Each test will score soon\&. Not total score for each test unless stupid module or no life\&. Worry if little or low score score after hacking\&. +.sp +If test break, but not repair, or maybe the dumb test, put the magic lines \fI_info\fR file like this\&. \fBccanlint\fR to score from 0 of 1 for test, but happy: +.sp +.if n \{\ +.RS 4 +.\} +.nf + * Ccanlint: + * // Test module foolish for me great! + * info_documentation_exists FAIL + * // Error for the file may be only + * tests_pass_valgrind_noleaks run\-mytest\&.c:FAIL +.fi +.if n \{\ +.RE +.\} +.PP +\fBinfo_exists\fR +.RS 4 +CCAN module must have +\fI_info\fR +file describing\&. No this score is 0\&. However, +\fBccanlint\fR +question may help to write one\&. +.RE +.PP +\fBdepends_exist\fR +.RS 4 + +\fI_info\fR +file CCAN other module without saying, must find\&. It is not score 0\&. +.RE +.PP +\fBobjects_build\fR +.RS 4 +All build purposes +\fI\&.c\fR +in the top dir\&. Not score 0\&. +.RE +.PP +\fBmodule_builds\fR +.RS 4 +Link to all objects in an object module\&. Not score 0\&. +.RE +.PP +\fBdepends_accurate\fR +.RS 4 +Include other CCAN modules, we must say we need to +\fI_info\fR +depends\&. Only one thing allows different, you can use +\fIccan/tap\fR +for testing anyway\&. +.RE +.PP +\fBdepends_build\fR +.RS 4 +We try to generate the CCAN module you need\&. +.RE +.PP +\fBexamples_exist\fR +.RS 4 +Rather hope that the comments in the header, and +\fI_info\fR\&. An example of the section in each, please! Maybe more, +\fBccanlint\fR +very happy morning\&. +.RE +.PP +\fBexamples_relevant\fR +.RS 4 +Example, do not cut and paste away! You say the name of the thing in the example or +\fBccanlint\fR +unhappy\&. +.RE +.PP +\fBhash_if\fR +.RS 4 +Module wants +\fBccanlint\fR +\fIconfig\&.h\fR +"#define HAVE_FEATURE" for all feature\&. Function test "#if HAVE_FEATURE" no "#ifdef HAVE_FEATURE" because user might not know about the role at all\&. Intelligent GCC flag +\fI\-Wundef\fR +say HAVE_FEATURE not 0, not 1! but only if the use of +\fI#if\fR\&. +.RE +.PP +\fBinfo_documentation_exists\fR +.RS 4 + +\fI_info\fR +file format is pretty comments\&. Copying someone\&. It is not difficult write documentation! +.RE +.PP +\fBinfo_summary_single_line\fR +.RS 4 +Comments from a top line often describe the function or macro\&. +\fI_info\fR +comment top line describes complete module\&. Characteristics make you scream! +.RE +.PP +\fBlicense_exists\fR +.RS 4 +The lawyers eat me\&. +\fI_info\fR +have +\fILicense:\fR +in the observation and LICENSE file there\&. In general, is the link: +\fBccanlint\fR +offer create a link, if they know +\fILicense:\fR\&. +.RE +.PP +\fBlicense_comment\fR +.RS 4 +Attorney everywhere\&. Please put a comment saying something like "GPL Version 4\&. Read LICENSE\&." in all source files in the directory\&. +.RE +.PP +\fBlicense_file_compat\fR +.RS 4 +Do not lie about the license! +\fBccanlint\fR +search files, see the license of another, angry here\&. +.RE +.PP +\fBlicense_depends_compat\fR +.RS 4 +Hostile to BSD license module, but requires another module of the GPL\&. Perhaps poor encoder think all BSD code, unloading and damage attorney stick! Ay ay! +.RE +.PP +\fBmain_header_exists\fR +.RS 4 + +\fBccanlint\fR +know the module name directory name\&. Expect the same name for header\&. +.RE +.PP +\fBheaders_idempotent\fR +.RS 4 +Good header +\fI#include\fR +many time happy\&. Rap header around easy\&. +\fBccanlint\fR +say it can fix too\&. Always work\&. +.RE +.PP +\fBmain_header_compiles\fR +.RS 4 +Simple program +\fI#include\fR +main header compile\&. +.RE +.PP +\fBavoids_cpp_reserved\fR +.RS 4 +C++ programmer to include code\&. Not like them anyway, maybe, but wrong end your program, do mourn\&. Only main header compile C++ and if trying to compile C\e++ module stupid to pieces\&. +.RE +.PP +\fBno_trailing_whitespace\fR +.RS 4 +Linux kernel programmers more, solve the problem for the space of the final ban the line\&. Now all lots of hackers working to fix it\&. Want to famous and Linux? Leave extra space too! +.RE +.PP +\fBexamples_compile\fR +.RS 4 + +\fBccanlint\fR +very smart! Take +\fIExample:\fR +from a comment in the header and +\fI_info\fR\&. First try to compile anything\&. If not, add many headers and maybe put inside the function\&. It does not work, adds the latest example\&. If the last example has +\fI\&...\fR +try that maybe\&. Sometimes too complicated! +\fI\-vv\fR +or +\fI\-\-keep\fR +to see why it broke\&. Or maybe bad example +\fBccanlint\fR +says wow! +.RE +.PP +\fBexamples_run\fR +.RS 4 +If the example program that comments like +\fI// given foo outputs bar\fR +\fBccanlint\fR +will run the food program +\fIfoo\fR +in the command line and standard input\&. Happy if +\fIbar\fR +are out\&. You can do \*(Aq or " about the production or determined\&. You can also +\fIoutput contains\fR +more relaxed controls\&. +.RE +.PP +\fBmodule_links\fR +.RS 4 +CCAN link to the program module simply no error\&. +.RE +.PP +\fBobjects_build_with_stringchecks\fR +.RS 4 +Module +\fIccan/str\fR +is super difficult to detect errors debugging chain\&. +\fBccanlint\fR +use with the module and see break! +.RE +.PP +\fBtests_exist\fR +.RS 4 +You have CCAN module directory called +\fItest\fR\&. You have proof here\&. If there is no proof, +\fBccanlint\fR +still offer make proof for you\&. +.RE +.PP +\fBtests_compile\fR +.RS 4 +In +\fItest\fR +which has four such tests, start with different name\&. +\fIrun\fR +compile the test files, but no link to the module, you +\fI#include\fR +to get the bits of the module\&. +\fIapi\fR +test compile and link with the module\&. +\fIcompile\-ok\fR +as +\fIrun\fR +but only build\&. +\fIcompile\-fail\fR +compile, but when +\fIFAIL\fR +set has to break or alert\&. This good for module supposed to warn\&. +.RE +.PP +\fBtest_helpers_compile\fR +.RS 4 +Other files +\fItest\fR? Compilation of links to all tests\&. Ask for help\&. +.RE +.PP +\fBtests_pass\fR +.RS 4 + +\fIrun\fR +and +\fIapi\fR +test happy departure\&. If not happy, offer debugger\&. +.RE +.PP +\fBtests_pass_valgrind\fR +.RS 4 + +\fBvalgrind\fR +the tool of all +\fIrun\fR +and +\fIapi\fR +slow test\&. However, we found many errors! If +\fBvalgrind\fR +test rest, +\fI_info\fR +have +\fBccanlint\fR +section, make "tests_pass_valgrind TESTNAME:FAIL"\&. If required valgrind additional option, "tests_pass_valgrind TESTNAME:\-\-option"\&. +.RE +.PP +\fBtests_pass_valgrind_noleaks\fR +.RS 4 + +\fBvalgrind\fR +complain if the memory leak test\&. +\fI_info\fR +can also be disabled\&. +.RE +.PP +\fBtests_compile_coverage\fR +.RS 4 +Compile +\fIrun\fR, +\fIapi\fR +test coverage\&. Fun if not here! +.RE +.PP +\fBtests_coverage\fR +.RS 4 +Run tests again, find lines that never try! Half of the lines 1 point 3/4 getting 2 points\&. Limit of 5 points, but the extra point for all lines of evidence\&. Not win unless the module silly or use gimmick +\fIccan/failtest\fR\&. +.RE +.PP +\fBreduce_features\fR +.RS 4 +Code use +\fIHAVE_FEATURE\fR +make special config\&.h turned off\&. Not stupid like HAVE_BIG_ENDIAN though! +.RE +.PP +\fBdepends_build_without_features\fR +.RS 4 +Make modules CCAN need\&. config\&.h but not more features\&. +.RE +.PP +\fBobjects_build_without_features\fR +.RS 4 +Make the module again, but not more features\&. +.RE +.PP +\fBtests_helpers_compile_without_features\fR +.RS 4 +Helpers do try again, but not more features\&. +.RE +.PP +\fBtests_compile_without_features\fR +.RS 4 +Collect the tests again, but not more features\&. +.RE +.sp +\fBtests_pass_without_features\fR: Run tests again, but not more features\&. +.SH "BUGS" +.sp +\fBccanlint\fR rapid change\&. The bad man, bad page\&. +.SH "AUTHOR" +.sp +Rusty Russell wrote \fBccanlint\fR\&. Helping others, but most break Rusty\&. +.SH "RESOURCES" +.sp +Main web site: http://ccodearchive\&.net/ +.sp +Wiki: https://github\&.com/rustyrussell/ccan/wiki/ +.SH "COPYING" +.sp +This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version\&. diff --git a/doc/ccanlint.1.txt b/doc/ccanlint.1.txt new file mode 100644 index 00000000..af3950c7 --- /dev/null +++ b/doc/ccanlint.1.txt @@ -0,0 +1,267 @@ +CCANLINT(1) +=========== +:doctype: manpage + + +NAME +---- +ccanlint - Make CCAN code modules, and the brightness up. + + +SYNOPSIS +-------- +*ccanlint* ['OPTIONS'] ['DIRECTORY'...] + + +DESCRIPTION +----------- +No encoder? No need to *ccanlint*. You programmer? Excited to *ccanlint*! + +CCAN module is small code of the song. *ccanlint* full CCAN testing +tool. Each test spray bit of wisdom. Also score. Good score good. +Bad bad score. + +*ccanlint* expect the source code in this directory, or command line can be +more than one. Exit 0 happy if all modules all tests happy. + +OPTIONS +------- +*-v, --verbose*:: + Make *ccanlint* talkative. "-vv" doing very talkative. "-vvvv" make stupid talker. + +*-n, --safe-mode*:: + Do not compile anything. Could it be safer for the bad code, but *ccanlint* + sad useless. + +*-l, --list-tests*:: + Tests show *ccanlint* can do. Then die happy. + +*--test-dep-graph*:: + Chart of all parties *ccanlint* tests 'dot(1)' Graphviz, then die happy. + +*-k, --keep*:: + *ccanlint* normally make mess temporary directory, but now it later in + forensic. + +*-s, --summary*:: + *ccanlint* just realized there is no message unless you die horrible. + +*-x, --exclude*='TESTNAME':: + No test run. Can the use of time many, many do *ccanlint* very, very quickly. + Often hatred 'tests_run_valgrind' that the test slowed. + +*--timeout*='MILLISECONDS':: + Stop the test and forget it if you take too long. Generally, the same works as + '-x tests_run_valgrind'. + +*-t, --target*='TESTNAME':: + Do not run all tests. Run this test, and the proof you need. Used many times + for many tests. + +*--compiler*='COMPILER':: + *ccanlint* read config.h about finding 'CCAN_COMPILER'. Otherwise use the default + when it was built. The change, to use this compiler. + +*--cflags*='CFLAGS':: + Set compiler options to compile. Be sure to protect spaces shell hunger. + + +TESTS +----- +*ccanlint* many tests. Each test will score soon. Not total score for +each test unless stupid module or no life. Worry if little or low +score score after hacking. + +If test break, but not repair, or maybe the dumb test, put the magic +lines '_info' file like this. *ccanlint* to score from 0 of 1 for +test, but happy: +--------------------------------------------------------------------- + * Ccanlint: + * // Test module foolish for me great! + * info_documentation_exists FAIL + * // Error for the file may be only + * tests_pass_valgrind_noleaks run-mytest.c:FAIL +--------------------------------------------------------------------- + +*info_exists*:: + CCAN module must have '_info' file describing. No this score is 0. + However, *ccanlint* question may help to write one. + +*depends_exist*:: + '_info' file CCAN other module without saying, must find. It is not score 0. + +*objects_build*:: + All build purposes '.c' in the top dir. Not score 0. + +*module_builds*:: + Link to all objects in an object module. Not score 0. + +*depends_accurate*:: + Include other CCAN modules, we must say we need to '_info' depends. + Only one thing allows different, you can use 'ccan/tap' for testing anyway. + +*depends_build*:: + We try to generate the CCAN module you need. + +*examples_exist*:: + Rather hope that the comments in the header, and '_info'. An + example of the section in each, please! Maybe more, *ccanlint* very + happy morning. + +*examples_relevant*:: + Example, do not cut and paste away! You say the name of the thing in + the example or *ccanlint* unhappy. + +*hash_if*:: + Module wants *ccanlint* 'config.h' "#define HAVE_FEATURE" for all + feature. Function test "#if HAVE_FEATURE" no "#ifdef HAVE_FEATURE" + because user might not know about the role at all. Intelligent GCC + flag '-Wundef' say HAVE_FEATURE not 0, not 1! but only if the + use of '#if'. + +*info_documentation_exists*:: + '_info' file format is pretty comments. Copying someone. It is not difficult + write documentation! + +*info_summary_single_line*:: + Comments from a top line often describe the function or macro. '_info' comment + top line describes complete module. Characteristics make you scream! + +*license_exists*:: + The lawyers eat me. '_info' have 'License:' in the observation and LICENSE + file there. In general, is the link: *ccanlint* offer create a link, if they + know 'License:'. + +*license_comment*:: + Attorney everywhere. Please put a comment saying something like "GPL + Version 4. Read LICENSE." in all source files in the directory. + +*license_file_compat*:: + Do not lie about the license! *ccanlint* search files, see the license + of another, angry here. + +*license_depends_compat*:: + Hostile to BSD license module, but requires another module of the GPL. + Perhaps poor encoder think all BSD code, unloading and damage + attorney stick! Ay ay! + +*main_header_exists*:: + *ccanlint* know the module name directory name. Expect the same name for + header. + +*headers_idempotent*:: + Good header '#include' many time happy. Rap header around easy. + *ccanlint* say it can fix too. Always work. + +*main_header_compiles*:: + Simple program '#include' main header compile. + +*avoids_cpp_reserved*:: + C\++ programmer to include code. Not like them anyway, maybe, but wrong + end your program, do mourn. Only main header compile C\++ and if + trying to compile C\++ module stupid to pieces. + +*no_trailing_whitespace*:: + Linux kernel programmers more, solve the problem for the space of + the final ban the line. Now all lots of hackers working to fix + it. Want to famous and Linux? Leave extra space too! + +*examples_compile*:: + *ccanlint* very smart! Take 'Example:' from a comment in the header and + '_info'. First try to compile anything. If not, add many + headers and maybe put inside the function. It does not work, adds + the latest example. If the last example has '...' try that maybe. Sometimes + too complicated! '-vv' or '--keep' to see why it broke. Or maybe + bad example *ccanlint* says wow! + +*examples_run*:: + If the example program that comments like '// given foo outputs bar' + *ccanlint* will run the food program 'foo' in the command line and + standard input. Happy if 'bar' are out. You can do ' or " about + the production or determined. You can also 'output contains' more + relaxed controls. + +*module_links*:: + CCAN link to the program module simply no error. + +*objects_build_with_stringchecks*:: + Module 'ccan/str' is super difficult to detect errors debugging chain. + *ccanlint* use with the module and see break! + +*tests_exist*:: + You have CCAN module directory called 'test'. You have proof + here. If there is no proof, *ccanlint* still offer make proof for + you. + +*tests_compile*:: + In 'test' which has four such tests, start with different + name. 'run' compile the test files, but no link to the module, you + '#include' to get the bits of the module. 'api' test compile and + link with the module. 'compile-ok' as 'run' but only build. + 'compile-fail' compile, but when 'FAIL' set has to break or + alert. This good for module supposed to warn. + +*test_helpers_compile*:: + Other files 'test'? Compilation of links to all tests. Ask for help. + +*tests_pass*:: + 'run' and 'api' test happy departure. If not happy, offer debugger. + +*tests_pass_valgrind*:: + *valgrind* the tool of all 'run' and 'api' slow test. However, we + found many errors! If *valgrind* test rest, '_info' have *ccanlint* section, + make "tests_pass_valgrind TESTNAME:FAIL". If required + valgrind additional option, "tests_pass_valgrind TESTNAME:--option". + +*tests_pass_valgrind_noleaks*:: + *valgrind* complain if the memory leak test. '_info' can also be disabled. + +*tests_compile_coverage*:: + Compile 'run', 'api' test coverage. Fun if not here! + +*tests_coverage*:: + Run tests again, find lines that never try! Half of the lines 1 + point 3/4 getting 2 points. Limit of 5 points, but the extra point + for all lines of evidence. Not win unless the module silly or use + gimmick 'ccan/failtest'. + +*reduce_features*:: + Code use 'HAVE_FEATURE' make special config.h turned off. Not + stupid like HAVE_BIG_ENDIAN though! + +*depends_build_without_features*:: + Make modules CCAN need. config.h but not more features. + +*objects_build_without_features*:: + Make the module again, but not more features. + +*tests_helpers_compile_without_features*:: + Helpers do try again, but not more features. + +*tests_compile_without_features*:: + Collect the tests again, but not more features. + +*tests_pass_without_features*: + Run tests again, but not more features. + +BUGS +---- +*ccanlint* rapid change. The bad man, bad page. + +AUTHOR +------ +Rusty Russell wrote *ccanlint*. Helping others, but most break Rusty. + + +RESOURCES +--------- +Main web site: http://ccodearchive.net/ + +Wiki: https://github.com/rustyrussell/ccan/wiki/ + +COPYING +------- +This program is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation; either version 2 of the License, or (at your option) +any later version. -- 2.39.2