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)