NAME

       bls-standalone - build log scanner, standalone version

SYNOPSIS

       bls-standalone --help

       bls-standalone  [  global  options  ]  check  [  --compiledrulesfile  rulesfile ] [ --blhc blhc-program ]
       logfiles

       bls-standalone [ global options ] compile [ compile-options ]

       bls-standalone [ global options ] checkout

DESCRIPTION

       bls-standalone is the command line utility to run the build log scanner on manually  specified  logfiles,
       including support to manage the needed compiled rules definitions.

GLOBAL OPTIONS

       Global options can be given before the command, available options are:

       Options  can  be specified before the command. Each affects a different subset of commands and is ignored
       by other commands.

       -v --verbose
              increase verbosity

       --libdir directory
              specify the directory where the scan and compile binaries are looked for

       --sharedir directory
              specify the directory where the copy of the rules files and the  packaged  precompiled  rule  data
              resides.

COMMANDS

       bls-standalone has three commands: check, compile and checkout.

       check [ --compiledrulesfile rulesfile ] [ --blhc blhc-program ] logfiles
              This  command  runs  the  bls  scanner  and  the blhc scanner on the given build log files.  If no
              compiled rules file is given with --compiledrulesfile then a previously compiled one is looked for
              and  if there is none than the one shipped together with the package is used.  blhc is also called
              if it is found or specified with the --blhcp option. To silence a warning about it not being found
              set it to NO.

       compile [ -o output-file ] [ --no-defaults] [ --ignorecheckout] additional rule descriptions
              Compiles the checks into a compiled form.

              Unless  -o  is given to determine a different place, it is stored in a cache directory (determined
              by some environment variables) where the future check invocations  will  use  it  intsead  of  the
              packaged precompiled rules.

              Additional rule descriptions can be given as command line arguments.

              Rules  stored  in proper places of your home directory are looked at, too.  (To see where they are
              looked for, use --verbose.)

              Unless --no-defaults is given the contents of a previous checkout or the copy of the rules shipped
              with the package are used, too.

              If  there  are  rules  of  the same name, those given as command line arguments override local and
              original ones and local ones override original ones.

       checkout
              Check out the current rules used for the non-standalone build scanner into a directory  where  the
              next compile run will use them instead of the shipped rules.

              Currently  this  checks  out  parts  of the QA svn repository.  This URL might get outdated in the
              future.  If the bls-standalone version you use and the non-standlone bls version get out of  sync,
              those rules might contain things that your bls-stanalone cannot handle.

WRITING RULES

       Some far too short guide to writing new description files:

       The non-standalone build log scanner is only run for builds deemed successful.  So checks for things that
       should usually make a build fail makes often not much sense (a test-suite generating false  positives  is
       often more likely than catching an error ignored inproperly).

       The  filename  is  the  tag  produced  for  the test. Finding a good name is often the hardest part about
       writing new checks.

       Most of the description file is actually the html code describing what the finding usually  means  to  be
       displayed  on  ⟨http://qa.debian.org/bls/⟩ with the exception of the lines starting with ## at the top of
       the file.

       The description should contain the following information:

   What did the check found?
       Make it easy for people to find what was matched. Makes it easier to  find  the  issue,  less  likely  to
       disregard it as false-positive if it is not, and less time wasting if it actually is a false positive.

   Why is what is found a problem?
       Even  the most serious flaws can easily be disregarded as minor issues due to ignorance.  And some things
       are only dangerous in some sitations  and  don't  require  the  highest  priority  in  other  situations.
       Distingushing both cases is hard and some more words in the description about it can help a lot.

   What can be done against it?
       Some  hints  how  to  avoid the problem both help the one due to fix it some time looking for a solution.
       This is especially useful to help people fixing it properly instead  of  only  hiding  the  problem  more
       thoroughly.

       The actual ## directives at the start of the file are:

   Merge:
       This line tells that this check triggers if other checks appear at the same line.

       There are currently only two forms supported:

        ##Merge: same tagname1 tagname2

       and

        ##Merge: same tagname1 tagname2a or tagname2b

   Match:
       This  is  a  regular  expression  describing what to match each line of the build log against to find the
       issue, prefixed with regexp:.  As an extension to the regular syntax there is a atom \/  which  specifies
       that  once  a line matches up to this part, no check that does not have a \/ at this place is supposed to
       match this line.  (This is an optimisation to heavily trim down the compile state machine,  but  it  also
       can be used to avoid false-positives).

       As all regular expressions of all checks are compiled into a single finite state machine, checks that are
       very specific at the start of the line are quite cheap while checks not specific at the start  are  often
       quite  expensive.   The size of the state machine output by the compile command is a good measurement how
       expensive the specific check is.

   Since:
       If there are new rules then the information at ⟨http://qa.debian.org/bls/⟩ might be  outdated  until  all
       logs  are  rescanned  with the new version.  For each log scanned by the non-standalone build log scanner
       the version number of the used rules is remembered.  The number specified with the Since field tells  the
       web report generated where to place warnings that information about this check might be outdated.

   Extract:
       This  tells  how to extract information from the matched file to be showed together with the matched line
       (like a filename something was found in).

       There are currently following forms supported here:

        ##Extract: simple 0 endcount 'endchar'
        ##Extract: simple 0 'reset' endcount 'endchar'
        ##Extract: simple startcount 'startchar' endcount 'endchar'
        ##Extract: simple startcount 'startchar' 'reset' endcount 'endchar'

       Where startchar is a character to look for for the start of the extracted area (after  the   startcountth
       occurrence).   resetchar  is a character to abort extraction.  endchar is a character to look for for the
       end of the extracted area (after the  endcountth occurrence).

       For example:
        ##Extract: simple 2 '|' '/' 1 '|' means to extract the content between the  2nd  and  3rd  pipe  symbol,
       unless there is a slash in between.

   Action:
       describes what to do if a switch is matched.  This can be used to set variables referenced in other rules
       to generate context-sensitive rules.

   Condition:
       add conditions (on variables set by ##Action).  If the condition is not met, the generating of a  finding
       is supressed.

CEVEATS

       While  compiling  all  matches  into a single finite state machine produces very fast results, it is only
       feasible while the state machine does not grow too much.  So  care  has  to  be  taken  to  not  use  too
       expensive searches.

       Some checks (especially context specific ones) are quite unreliable.  The non-standalone build log checks
       do not include some findings for the summary unless they appear on  multiple  architectures,  which  bls-
       standalone obviously cannot do.

       bls  is optimized to be fast.  Do not run it with rules files you do not trust.  (Only the content of log
       files scanned is supposed to be untrusted data).

       blhc is quite slow which is luckily not that noticeable  if  not  scanning  the  logfiles  of  the  whole
       archive.  If  you test new rules on a larger set of logfiles, using --blhc=NO can speed things up quite a
       bit.

       blhc does not report line numbers so bls-standalone cannot report them for those findings.

       Note that checking the logs of a dpkg-buildpackage -b run and a  dpkg-buildpackage  -B  run  can  make  a
       difference  (so if you cannot reproduce a E-binary-arch-produces-all make sure you check the correct type
       of log).

REPORTING BUGS

       Report bugs or wishlist requests to the Debian BTS
       (e.g. by using reportbug bls-standalone under Debian)
       or directly to brlink@debian.org

COPYRIGHT

       Copyright © 2013,2014,2015 Bernhard R. Link ⟨http://www.brlink.eu⟩
       This is free software; see the source for  copying  conditions.  There  is  NO  warranty;  not  even  for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       blhc(1)