BLS-STANDALONE(1)

💖 BLS-STANDALONE(1) 💖

hiii bestie 🫶 welcome to section 1 of the manual for bls-standalone — the build log scanner, standalone version. she's a command line girlie, she's iconic, and she's about to make your build logs make sense. let's get into it 💅

---

✨ NAME ✨

bls-standalone — build log scanner, standalone version. that's the whole vibe. 🦋

---

✨ SYNOPSIS ✨

okay so here's how you talk to her:

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 ✨

so bls-standalone is the command line utility that runs the build log scanner on logfiles you picked out yourself, manually, with your own two hands 💖. and because that's not enough main character energy, she also has support for managing the compiled rules definitions she needs. she's self-sufficient like that. periodt. 👑

---

✨ GLOBAL OPTIONS ✨

these are the global girlies — you give them before the command. here's what's available:

also quick note, bestie: options can be specified before the command. each one affects a different subset of commands and is ignored by the other commands. so like, don't stress, she's just built like that. 🙈

• -v, --verbose — increase verbosity. she'll start yapping (affectionate) ✨
• --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, and they are: check, compile and checkout. a trio. a little squad. 🫶

🩺 check

check [ --compiledrulesfile rulesfile ] [ --blhc blhc-program ] logfiles

this command runs the bls scanner and the blhc scanner on the given build log files. so she's doing double duty, no big deal 💅

if no compiled rules file is given with --compiledrulesfile then a previously compiled one is looked for, and if there is none then the one shipped together with the package is used. she'll find something, she always does.

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. (yes bestie, that's how you shush the warning, you literally just say NO 😌)

🧚 compile

compile [ -o output-file ] [ --no-defaults] [ --ignorecheckout] additional rule descriptions

compiles the checks into a compiled form. it's giving "prep work but make it fast later" ✨

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. (yes, "intsead". we don't fix, we preserve 🫡)

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.) so if you're nosy like me, that's your moment 🔍

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

and 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. hierarchy. slay. 👑

🛒 checkout

checkout

checks 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. (ngl, kind of ominous but okay 🙈)

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. so like… vibe check your versions, bestie. 💀

---

✨ WRITING RULES ✨

some far too short guide to writing new description files. she said "short" and she meant it, but let's go 🌸

the non-standalone build log scanner is only run for builds deemed successful. so checks for things that should usually make a build fail make often not much sense (a test-suite generating false positives is often more likely than catching an error ignored inproperly). yeah. read that twice. it's real. 😭

the filename is the tag produced for the test. finding a good name is often the hardest part about writing new checks. naming things is always the hardest part, no cap.

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. be clear, be kind, be specific 💖

🌟 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. context is everything bestie, spell it out 🫶

🌟 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. (hiding ≠ fixing, we've all been there 🙈)

---

📜 the actual ## directives

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.) two birds, one stone, iconic ✨

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. so like, watch your state machine's waistline 👀

🎀 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. timestamps for the girlies ⏰

🎀 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 *endcount*th 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. see? not scary at all 🎀

🎀 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 💀

(this heading is spelled exactly like that, and we respect her. moving on.)

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. don't let it get bloated bestie 🫶

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. she's doing her best 😭

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). like, seriously. that's the reddest flag in this whole page. 🚩

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. little hack, big payoff ✨

blhc does not report line numbers so bls-standalone cannot report them for those findings. not her fault, she's just the messenger 🙈

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). lowercase b vs uppercase B. one character. huge consequences. 💅

---

🐛 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. (she said NO warranty and she meant it, capitalize-and-all 🫡)

---

👀 SEE ALSO 👀

blhc(1)

---

🌈 and that's the whole page, bestie!! this was bls-standalone, version 2015-12-31, from the BLS-STANDALONE(1) manual — thanks for reading all the way to the bottom, you're literally the main character for that 💖✨🎀🦋💅