home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tlint1_0.zip / tlint1_0 / doc / lnt10hlp.txt < prev    next >
Text File  |  1996-02-05  |  17KB  |  472 lines
  1. LINT - C source code checker.
  2. Syntax:
  3.           tlint [file] [option]*
  4.  
  5.           (+|-)ControlComments (-)  (+|-)Declarations (-)
  6.           (+|-)Keep (-)             (+|-)StandardLibrary (+)
  7.           (+|-)Verbose (-)          (+|-)Wide (-)
  8.           Configuration=file        CrossReference=keyword
  9.           Define=name=value         Include=directory
  10.           INSTallation=file         Library=lib
  11.           libraryName=string        Output=file
  12.           Output+=file              StandardInclude=directory
  13.           StandardLibrary=name      Summary=file
  14.           Target=keyword            indeX=file
  15.  
  16. Examples:
  17.           tlint myfile
  18.           tlint x=files o=incls ln=proj def=PROJECT=1
  19.  
  20. Options:
  21. file
  22.      is a  source file containing C code.  The other options
  23.      on the  command line  determine whether LINT scans this
  24.      file for  problem spots,  or uses  the file to create a
  25.      summary or an entry in a LINT library.
  26.  
  27. indeX=file
  28.      gives the  name of a text file.  Each line in this text
  29.      file should  contain the  name of  one C  source  file.
  30.      LINT checks  each of  these source  files individually.
  31.      In addition  to a  source file name, a line in an index
  32.      file  may   specify  ControlComments,   Configuration=,
  33.      Include= and Define= options.  These options only apply
  34.      to the  source file  named  on  the  same  line.    For
  35.      example, if the line
  36.  
  37.         myfile define=VERSION=1
  38.  
  39.      appeared in  an index  file, LINT  would use  the given
  40.      option when  examining myfile  but not  for other files
  41.      named in  the index  file.   When processing  an  index
  42.      line, LINT  normally uses  all the options appearing on
  43.      the  main   command  line,   followed  by  the  options
  44.      specified on  the index  line.    As  a  special  case,
  45.      however, Include=  options on  a line  in an index file
  46.      are used  before  any  Include=  options  on  the  LINT
  47.      command line.  Only one indeX= option may appear on the
  48.      command line.
  49.  
  50. Configuration=file
  51.      specifies a  configuration file  for LINT.    For  more
  52.      information on configuration files, see below.
  53.  
  54. +ControlComments
  55.      indicates that control comments of the type
  56.  
  57.         /*VARARGS*/
  58.  
  59.      should be  processed.  The default is -ControlComments,
  60.      in  which   case  such   comments  are   ignored.     A
  61.      ControlComments option  on a  line  in  an  index  file
  62.      overrides any  ControlComments option  on the main LINT
  63.      command line.
  64.  
  65. CrossReference=keyword
  66.      indicates that  LINT output  should  include  a  cross-
  67.      reference table  that shows  where symbols are defined,
  68.      referenced,  set,   and  used.   (By  default,   cross-
  69.      references are  not provided.)  Possible values for the
  70.      keyword are:
  71.  
  72.      All - cross-references all symbols;
  73.  
  74.      External - only cross-references external symbols.
  75.  
  76. +Declarations
  77.      may be  used when  creating a  LINT library  or summary
  78.      file.   With this  option, LINT treats every file scope
  79.      declaration  as   if  it  were  a  definition  for  the
  80.      variable, instead of a simple reference.
  81.  
  82. Define=name=value
  83.      has the same effect as
  84.  
  85.         #define name value
  86.  
  87.      in the C source code.  The option indicates that "name"
  88.      should be  replaced with  "value" (as text) wherever it
  89.      appears in  the source code being examined.  If "value"
  90.      contains  blanks   or  tab  characters,  it  should  be
  91.      enclosed in double or single quotes.
  92.  
  93. Include=directory
  94.      is the  same as the Include= option for the C compiler.
  95.      When LINT tries to find quoted include files, as in
  96.  
  97.         #include "file"
  98.  
  99.      it begins  by searching  the given  directory  for  the
  100.      file.   If the  file is  not found there, LINT searches
  101.      any directory  named in  StandardInclude= options,  and
  102.      finally searches the directory that contains the source
  103.      file being  examined.   Any number  of Include= options
  104.      may be  specified.   Directories are  searched  in  the
  105.      order given on the command line.
  106.  
  107. INSTallation=file
  108.      tells LINT  where to  find the  installation file.  The
  109.      installation  file   tells   where   various   software
  110.      components have  been installed.  For more information,
  111.      see the section on Installation Files below.
  112.  
  113.      If you  do not  specify an  INSTallation= option on the
  114.      command line,  LINT checks  for an environment variable
  115.      named LINT_INST  and uses  its value as the name of the
  116.      installation file.   If  this environment variable does
  117.      not exist, LINT uses the default installation file.
  118.  
  119. +Keep
  120.      does  not   delete  intermediate   files  left  by  the
  121.      preprocessor and the LINT steps.
  122.  
  123. Library=lib
  124.      names a  LINT library that should be used when checking
  125.      source code.  Any number of Library= options may appear
  126.      on the  command line.   By  default, LINT automatically
  127.      includes LINT  libraries of  standard C functions (e.g.
  128.      printf) so that such functions are always recognized.
  129.  
  130. libraryName=string
  131.      is used  when creating  a LINT  library.  See below for
  132.      more details.
  133.  
  134. Output=file
  135.      is used  when creating  a LINT  library or summary file
  136.      (see below).   The output overwrites the file's current
  137.      contents.
  138.  
  139. Output+=file
  140.      is the  same as  Output=file,  except  that  output  is
  141.      written to  the end  of the  current  contents  of  the
  142.      specified file,  rather than  overwriting what the file
  143.      already holds.
  144.  
  145. StandardInclude=directory
  146.      is the  same as  the StandardInclude=  option for the C
  147.      compiler.   When LINT tries to find include files whose
  148.      names are enclosed in angle brackets, as in
  149.  
  150.         #include <file>
  151.      it begins  by searching  the given  directory  for  the
  152.      file.   If the  file is  not found there, LINT searches
  153.      directories named  in  Include=  options,  and  finally
  154.      searches the  directory that  contains the  source file
  155.      being examined.  Any number of StandardInclude= options
  156.      may be  specified.   Directories are  searched  in  the
  157.      order given on the command line.
  158.  
  159. StandardLibrary=name
  160.      asks LINT  to include the standard library indicated by
  161.      "name". The following names are recognized:
  162.  
  163.      C  -   the  standard   C  library.   This  is  included
  164.      automatically, unless -StandardLibrary is specified.
  165.  
  166. -StandardLibrary
  167.      does not include the standard C library routines.
  168.  
  169. Summary=file
  170.      states that  the given  file is  a  summary  file  that
  171.      should be  used as  input to  the LINT  operation.  See
  172.      below for more on summary files.
  173.  
  174. Target=keyword
  175.      controls the  kind of  problem-checking you want to do.
  176.      The following keywords are recognized.
  177.  
  178.      Host -  describes any  problems that  may arise  if the
  179.      program is  run on  the host  machine (i.e. the machine
  180.      where you are running LINT).  This is the default.
  181.  
  182.      Extensions -  points out any extensions to C that might
  183.      have been  used, as well as any machine-dependencies in
  184.      the code.  It also describes the problems detected with
  185.      Target=Host.
  186.  
  187.      Minimal -  points  out  any  features  that  may  cause
  188.      problems  if  you  port  this  program  to  a  non-ANSI
  189.      compiler.   This will  make note  of all  ANSI features
  190.      used.   It also  describes the  problems detected  with
  191.      Target=Extensions.
  192.  
  193. +Verbose
  194.      prints out  the name  of the  file being examined.  The
  195.      default is -Verbose.
  196.  
  197. +Wide
  198.      prints output  in a  format that  is 132  columns wide.
  199.      The default  is -Wide,  which prints  in  an  80-column
  200.      format.
  201.  
  202. Abbreviating Options:
  203.  
  204.     The option  keywords given  above can  be abbreviated by
  205. omitting any or all of the letters shown in lower case.  For
  206. example, CrossReference=All may be abbreviated to
  207.  
  208.           crossref=all
  209.           cref=all
  210.           cr=all
  211.           cr=a
  212.  
  213. and so  on.   When entering  option keywords,  you may  type
  214. letters in upper, lower, or mixed case; the use of upper and
  215. lower case  in this  documentation is  simply to  show  what
  216. letters are and aren't required.
  217.  
  218. Description:
  219.     LINT checks  C source  code for "irregularities": errors
  220. and  non-portable   constructions.  Diagnostics   from  LINT
  221. normally take the form
  222.  
  223.           filename,lineno: class: message
  224.  
  225. where "filename"  is the name of the file that contained the
  226. problem and  "lineno" is  the number  of the line within the
  227. file.   The "class"  describes what type of message this is:
  228. warning, error,  etc.   If a diagnostic refers to a function
  229. or external  variable in  a LINT  library, the  form of  the
  230. diagnostic is
  231.  
  232.           libname:message
  233.  
  234. where "libname" is the name of the LINT library.
  235.  
  236.     Unless your  program is  very small,  LINT will probably
  237. produce a  great deal  of output.   You will usually find it
  238. convenient to  redirect LINT's output into a file instead of
  239. letting it be displayed on the terminal screen.  To do this,
  240. just put ">filename" on the LINT command line, as in
  241.  
  242.           tlint myprog >output
  243.  
  244. This tells LINT to write its output into the given file.
  245.  
  246.  
  247. Other Ways to Use LINT
  248.  
  249.     In addition  to checking C code for irregularities, LINT
  250. can:
  251.  
  252. (a)  Extract a  summary file of information that can be used
  253.      in other LINT operations.
  254.  
  255. (b)  Create a LINT library.
  256.  
  257. Summary files and LINT libraries are discussed below.
  258.  
  259.  
  260. Summary Files
  261.  
  262.     A summary file contains a "summary" of your source code:
  263. the names  and types  of  all  the  external  variables  and
  264. functions defined  or referenced in the code, plus any other
  265. information LINT  may need  when checking  the code (such as
  266. the declared  types of  function parameters).  Summary files
  267. also record any error messages that might be issued by the C
  268. compiler  when  parsing  the  source  code.    All  of  this
  269. information is  stored in  a  special  format  that  is  not
  270. directly readable by humans.
  271.  
  272.     To create a summary file from a normal source code file,
  273. use the Output=file option, as in
  274.  
  275.           tlint src1.c output=summ
  276.  
  277. You can  add more  material to  the same  summary file using
  278. Output+=file, as in
  279.  
  280.           tlint src2.c output+=summ
  281.  
  282. This appends  new material  to the  existing contents of the
  283. summary file.
  284.  
  285.     When LINT  creates a  Summary file, LINT only summarizes
  286. your source  code and checks for syntax errors.  It does not
  287. check for  such problems  as non-portable constructs or type
  288. mismatches.   However, you  can run  a summary  file through
  289. LINT again to do standard type-checking.  For example,
  290.  
  291.           tlint srcfile output=lf
  292.           tlint summ=lf
  293.  
  294. creates a  summary file,  then uses  the information  in the
  295. summary file  to see if types match in symbol references and
  296. definitions.
  297.  
  298.     The reason for creating summary files is the same as the
  299. reason for  breaking up the source code of your program into
  300. several source  files: it is easier to deal with source code
  301. in small pieces than in one big hunk.  Some users may keep a
  302. summary file  for every  source file.   If  the code  in one
  303. source file  is changed,  you can create a summary file from
  304. that source  file, then  run all  the summary  files of  the
  305. program through  LINT to  see if  the change  has caused any
  306. problems.   This is  much faster  than using LINT on all the
  307. raw source code.
  308.  
  309.  
  310. LINT Libraries
  311.  
  312.     A LINT  library is similar to a summary file, in that it
  313. contains  a  summary  of  C  source  code.    However,  LINT
  314. libraries are  intended to  parallel  the  way  that  object
  315. libraries work.
  316.  
  317.     To create  a LINT  library,  specify  both  the  Output=
  318. option and the libraryName= option on the LINT command line.
  319. For example,
  320.  
  321.           tlint file output=mylib libname="abc"
  322.  
  323. creates a  LINT library  named abc  in the  file mylib. This
  324. name is  used in LINT diagnostic messages related to symbols
  325. found in  the LINT  library.   Using LINT  in this  way only
  326. generates minimal  messages; full  messages are printed when
  327. you actually use the LINT library.
  328.  
  329.     To use  a LINT  library, specify  the Library= option on
  330. the LINT command line, as in
  331.  
  332.           tlint myfile library=mylib
  333.  
  334. When LINT  finds that  myfile contains  a  reference  to  an
  335. undefined symbol,  LINT checks  the information in the given
  336. LINT library  to see  if the  symbol is defined there.  This
  337. works just  like compiling  a module  while referring  to an
  338. object library.   No  error occurs  if a  symbol in the LINT
  339. library has  the same  name as  a symbol in the source file;
  340. the source file symbol is the one that is used.
  341.  
  342.     Functions should  only be  placed in a LINT library when
  343. you are sure they contain no errors.  LINT does not look for
  344. errors when it is creating a LINT library.
  345.  
  346.  
  347. Review of Inputs and Outputs
  348.  
  349.     To specify  a file  as an  input, simply give the file's
  350. name.  To specify a summary file as input, use Summary=file.
  351. To specify  a LINT library as input, use Library=file.  LINT
  352. uses all of the contents of a source file or a summary file;
  353. it only  uses library  entries if  they  are  referenced  by
  354. source code or a summary file.
  355.  
  356.     An index  file contains partial command lines to be used
  357. by LINT  in its  operations.   These command  lines can name
  358. source files  as  input,  but  not  summary  files  or  LINT
  359. libraries.
  360.  
  361.     When  both   an  Output=  and  libraryName=  option  are
  362. specified, LINT  creates a LINT library.  If only Output= is
  363. specified, LINT  creates a  summary file.  If Output= is not
  364. specified, LINT  examines a  source file or summary file for
  365. problem spots  and writes  its diagnostics  to the  standard
  366. output.
  367.  
  368.  
  369. Multiple Definitions
  370.  
  371.     If LINT  finds two  definitions for the same function or
  372. external variable,  it always  outputs a diagnostic message.
  373. If the  two definitions are both in normal source code, LINT
  374. arbitrarily chooses  the first  definition it  finds as  the
  375. "correct" definition,  and issues  diagnostics for any later
  376. deviations  from  this  definition.    If  one  of  the  two
  377. definitions is  in a LINT library and the other is in normal
  378. source code,  LINT chooses  the non-library  version as  the
  379. "correct" definition.   In  this way, a definition in normal
  380. source code overrides a library definition.
  381.  
  382.  
  383. Configuration Files
  384.  
  385.     A configuration  file consists of a series of directives
  386. that control  the behavior of LINT.  The possible directives
  387. are explained below.
  388.  
  389. define name string
  390.      has the  same format and purpose as a #define directive
  391.      in normal  C code.  It creates a manifest or macro with
  392.      the given value.
  393.  
  394. inline includefile
  395.      lets you  simulate an include file.  When LINT finds an
  396.      inline directive,  it begins  to gather  input lines up
  397.      until  the   first  line   consisting  of  only  a  '#'
  398.      character.  For example, in
  399.  
  400.         inline sim.h
  401.         extern int junk1;
  402.         extern int junk2;
  403.         #
  404.  
  405.      LINT collects  the two declarations and associates them
  406.      with the  name "sim.h".   If  a  program  contains  the
  407.      directive,
  408.  
  409.         #include <sim.h>
  410.  
  411.      LINT takes  the gathered  text and  includes it at that
  412.      point in  the program,  as  if  it  had  come  from  an
  413.      included file.
  414.  
  415. map includename1 includename2
  416.      says that all references of the form
  417.  
  418.         #include includename1
  419.  
  420.      should be converted to
  421.  
  422.         #include includename2
  423.  
  424. null includefile
  425.      tells LINT  to  ignore  all  #include  directives  that
  426.      attempt to include the specified file.
  427.  
  428. search pathname
  429.      is equivalent  to Include=pathname  on the LINT command
  430.      line.
  431.  
  432. system_search pathname
  433.      is equivalent  to StandardInclude=pathname  on the LINT
  434.      command line.
  435.  
  436. Installation Files:
  437.     An  installation   file  specifies   the  pathnames  for
  438. software and  data files  used by  LINT.  Installation files
  439. are text files made up of comment lines and option lines.
  440.  
  441. Comment lines:
  442.      Any line  whose first  non-blank character is # will be
  443.      taken as  a comment.   Blank  lines are also considered
  444.      comments.
  445.  
  446. Option lines:
  447.      Option lines have the format
  448.  
  449.           Keyword=pathname
  450.  
  451.      In this  documentation, keywords  are written with some
  452.      letters in  upper case and some in lower case.  You may
  453.      abbreviate keywords  by omitting  any  or  all  of  the
  454.      letters shown in lower case.  The remaining letters may
  455.      be  entered   in  either   upper  or  lower  case;  the
  456.      documentation simply  uses upper  case  to  show  which
  457.      characters may not be omitted.
  458.  
  459.     In this version of LINT, possible option lines are:
  460.  
  461. Include=pathname
  462.      gives the directory containing the LINT include files.
  463.  
  464. Library=pathname
  465.      gives the directory containing the LINT libraries.
  466.  
  467. Program=pathname
  468.      gives the  directory  containing  the  LINT  executable
  469.      files (CPP, and so on).
  470.  
  471. Copyright 1995, by Thinkage Ltd.
  472.