debian: Add two missing files.

These were missed to add when Steve's patch against an older commit
was converted into an incremental patch on top of b4d4de17a5c8.
This bug is mine, not Steve's.

Fixes: b156a0cabd42582e9c430ae4a284f8815746914e

build: Honor LDFLAGS

It's good practice to include CPPFLAGS, CFLAGS and LDFLAGS in the
rules which invoke the linker. We already do this for the former two,
so do the same with LDFLAGS as well.

Switch to https.

All URLs of the source code work as well with the https transport,
which is generally preferred. The links in the files below debian/
will be adjusted in a separate commit.

lopsubgen.suite: Fix homepage link.

There is no tilde in the URL. This affects the lopbsupgen man page.

debian: Final version of 64-bit time_t transition.

This partially reverts reverts commit b4d4de17a5c8, replacing it with
the version that has been uploaded to unstable.

It adds a versioned build-dependency on dpkg-dev to guard against
accidental backports with a wrong ABI.

Signed-off-by: Andre Noll <maan@tuebingen.mpg.de>

Add target to create a static library.

It's sometimes handy to create a static version of the library,
although this is generally frowned upon. No standard target depends
on the new liblopsub.a target, so the static library is not build by
default. One has to explicitly run "make liblopsub.a" to build it.

debian: 64-bit time_t transition.

As part of the 64-bit time_t transition required
to support 32-bit architectures in 2038 and beyond
(https://wiki.debian.org/ReleaseGoals/64bit-time), we have identified
liblopsub as a source package shipping runtime libraries whose ABI
either is affected by the change in size of time_t, or could not be
analyzed via abi-compliance-checker (and therefore to be on the safe
side we assume is affected).

To ensure that inconsistent combinations of libraries with their
reverse-dependencies are never installed together, it is necessary
to have a library transition, which is most easily done by renaming
the runtime library package.

Since turning on 64-bit time_t is being handled
centrally through a change to the default dpkg-buildflags
(https://bugs.debian.org/1037136), it is important that libraries
affected by this ABI change all be uploaded close together in time.
Therefore I have prepared a 0-day NMU for liblopsub which will
initially be uploaded to experimental if possible, then to unstable
after packages have cleared binary NEW.

Signed-off-by: Andre Noll <maan@tuebingen.mpg.de>

Fix flag option parsing bug in config file parser.

The old code misparses the config file if it contains a flag option
which is followed by a newline which starts with whitespace. In this
case, since newlines belong to the [[:space:]] class, the option is
regarded as an option with argumment.

Fix this by s/:space:/:blank:/. The [[:blank:]] class only contains
space and tab. which is what the code expects.

Fix typo in config file test program.

This code is #ifdef'ed out, so the typo was never noticed. Add a
comment which explains how to create a binary from the .l file while
at it.

Don't print invalid line numbers in error messages.

If yylex() fails, yyget_lineno() should not be called because it
accesses uninitialized memory:

==23686== Use of uninitialised value of size 4
==23686==    at 0x46FA85D: _itoa_word (_itoa.c:178)
==23686==    by 0x4704E14: __printf_buffer (vfprintf-process-arg.c:155)
==23686==    by 0x471B91C: __vsprintf_internal (iovsprintf.c:62)
==23686==    by 0x47010DD: sprintf (sprintf.c:30)
==23686==    by 0x45A019F: lls_convert_config (config_file.l:272)
==23686==    by 0x804F0BA: parse_options (misma.c:741)
==23686==    by 0x804A879: main (misma.c:1529)

Just omit printing the line number for now.

Makefile: Include Makefile.local if it exists.

This provides a way to support local recipes.

lopsub-1.0.4

lls_parse_arg(): Avoid NULL pointer dereference.

If a string option with multiple=false is given twice at the command
line, the second and all subsequent calls to lls_parse_arg() discard
the previous value stored in lor->value[0].

However, if the option takes an optional argument and was first
specified without argument, lor->value remains NULL because the
first call to lls_parse_arg() returned early due to the shortcut
at the beginning of the function while the second call skips the
allocation because lor->given is increased also when no argument is
given, so it equals one during the second call. Thus, the attempt
to free lor->value[0] further down in the function results in a NULL
pointer dereference.

Fix this by checking lor->value rather then lor->given. To make this
work we have to move up the code which frees the old string value.

While at it, reduce memory usage by not over-sizing the array. We
now only allocate space for idx + 1 values rather than lor->given +
1. This is different in the case mentioned above.

Improve error message of lls_check_arg_count().

When min_argc == max_argc, the function checks whether exactly this
many arguments are given. In the error case, it says

exactly N non-option args allowed, M given

which reads a bit weird. With the patch applied the message becomes

exactly N non-option args required, M given

Fix documentation of [introduction] and [conclusion].

These texts should *not* contain roff source code.

Makefile: Add -ffile-prefix-map to CC to avoid embedding build paths.

Signed-off-by: Andre Noll <maan@tuebingen.mpg.de>

Merge branch 't/build-improvements'

The build system fails in unexpected ways when required programs like
m4 or flex are not installed. One particular problem is a construct
of the form

    $(M4) ... > $@

in the recipe of the lopsub.h target. If m4 is not installed, this
results in an empty lopsub.h file, which is considered up-to-date
by subsequent runs of make(1). The subsequent compilation of lsg.c
succeeds despite of the empty lopsub.h, but the resulting executable
segfaults.

The reason is that lsg1.c includes lopsub.h to declare lls_version(),
but due to lopsub.h being empty, the declaration is missing and the
compiler implicitly assumes an int return value rather than char *.

This patch series addresses this problem in several ways. With the
series applied:

* the build fails early if m4 or flex are not installed,
* missing function declarations are considered errors rather than warnings,
* incompletely written targets are removed by make(1).

build: Error out on implicit function declarations.

Replacing lopsub.h by an empty file builds a buggy lopsubgen-stage1
executable which segfaults due to a format string mismatch caused
by the implicit declaration of lls_version(). In this package all
functions are supposed to be declared, so let's fail the build if
any undeclared functions are found.

Tested-by: Alex Gietz <oss@mcdinner.de>

build: Improve handling of compiler options.

Introduce LLS_CFLAGS and STRICT_CFLAGS to avoid duplicating the flags
in the various cc recipes. We don't touch CFLAGS or CPPFLAGS in the
Makefile but include it the cc commands to let the user override
our settings.

build: Activate .DELETE_ON_ERROR.

Since m4 lacks the -o option to specify an output file, we redirect
stdout in several recipes, in particular in the recipe that creates
lopsub.h from lopsub.h.m4. If the m4 command fails, lopsub.h will
be incomplete or empty, yet it will be considered as up-to-date
by make(1).

This patch teaches make(1) to remove such incomplete output files
on errors.

build: Bail out early if m4 or lex don't exist.

This gives a decent error message on the attempt to run make(1) on a
system where one or both of these essential programs are not installed.

A previous version of the patch used .SHELLSTATUS instead of the
dummy variable, but this did not work with make-4.1 which ships
with Ubuntu-18.04.

Suggested-by: Alex Gietz <oss@mcdinner.de>

build: Remove duplicate -g in cc command.

Specifying -g more than once has no effect.

build: Avoid "html" rule with empty recipe.

This was over-engineered, and only one of the three rules which
create .html files depends on both the header and the footer.

Fix build target www.

This target is supposed to create the html files of the home page.
This broke one year ago when the build system was instructed to create
compressed man pages. Fortunately, the fix is trivial.

Fixes: f35b70fc3e8656f71437cc85062da31488acd781

Fix three typos.

These were pointed out by lintian. See the lintian report page:

https://lintian.debian.org/full/maan@tuebingen.mpg.de.html

Make the build reproducible.

Whilst working on the Reproducible Builds effort [0] we noticed that
liblopsub could not be built reproducibly.

This is because it calls "gzip" manually without the -n
flag. This should have been reported by lintian via the
package-contains-timestamped-gzip tag.

  [0] https://reproducible-builds.org/

lopsub-1.0.3-2

Bump the debian version number to quickly land the two recent fixes
for reproducible builds.

Makefile: Get rid of superfluous '+' character in date.

Commit bb3a974325f (Don't embed compile-time timestamps into generated
files) from a couple of weeks ago introduced a leading '+' in case
SOURCE_DATE_EPOCH is not set because DATE_FMT already contains the
'+' character for the argument to date(1), The superfluous '+'
becomes part of the generated man pages, which looks a bit weird.

lsg.c: Make the output of lopsubgen reproducible.

Whilst working on the Reproducible Builds effort [0], we noticed that
liblopsub generates output that is not reproducible. The lopsubgen
utility does not respect SOURCE_DATE_EPOCH [1] and thus packages such
as src:tfortune are rendered unreproducible as they then encode the
build date and time.

This patch makes lopsubgen honour SOURCE_DATE_EPOCH.

[0] https://reproducible-builds.org/
[1] https://reproducible-builds.org/specs/source-date-epoch/

Signed-off-by: Andre Noll <maan@tuebingen.mpg.de>

Don't embed compile-time timestamps into generated files.

Currently the build is not reproducible because make(1) runs
date(1) to provide the month and the year for the man page. Fix
this by honouring SOURCE_DATE_EPOCH as described in

https://reproducible-builds.org/specs/source-date-epoch/

Signed-off-by: Andre Noll <maan@tuebingen.mpg.de>

lopsub 1.0.3

Merge branches 't/debian', 't/dynamic-lib', 't/lls_check_arg_count' and 't/news'

This octopus merge combines four branches, two of which were created
with the aim of making the package acceptable for inclusion into
Debian: The t/dynamic-lib branch instructs make to create a dynamic
library instead of the static one, the t/debian branch adds the usual
files below debian/.

The remaining two branches, t/lls_check_arg_count and t/news, contain
only a single commit each. The first improves the wording of an error
message while the second introduces the NEWS file, respectively.

The tree which corresponds to this commit was accepted for Debian
unstable on May 15 2019 as version 1.0.2-1.

Add NEWS file containing release notes.

It's nice to have a concise overview of the changes.

Add infrastructure to build debian packages.

This commit adds the usual files below debian/ so that two debian
binary packages, liblopsub1 and liblopsub1-dev, can be made with a
command like

dpkg-buildpackage

The bulk of the recipes in debian/rules employ debhelper(7).

This has been tested on debian-9 and debian-10. On both systems,
lintian(1) reports no warnings and no errors.

v4 -> v5
~~~~~~~~
Avoid the term "all-permissive license" to address copyright concerns
pointed out by Thorsten Alteholz.

v3 -> v4
~~~~~~~~
Next round of feedback from Adam Borowski:
 * soname-less source package
 * Full description for liblopsub-dev
 * debian/changelog: UNRELEASED -> unstable

v2 -> v3
~~~~~~~~
Incorporate more feedback from Adam Borowski:
 * version-gen.sh now works also without a git repository
 * The soname has been dropped from the name of the development package
 * library files are installed in the multiarch dir /usr/lib/$triplet

v1 -> v2
~~~~~~~~
Incorporate review comments from Adam Borowski:
 * Rename package name from lopsub to liblopsub1 to make lintian happy.
 * Append "-1" to the debian version to make it a non-native package.
 * Switch source format from "3.0 (native)" to "3.0 (quilt)".
 * Mention what parts are GPLv3-ed and which are LGPLv3-ed.
 * Adjustments for building a shared library.
 * Squash remaining lintian warnings.

rewrite de/copyright

lopsub.7: Avoid the term "all-permissive license".

As pointed out by Thorsten Alteholz, we use the term without really
explaining it. Replace it with "public domain", which is well-defined
and conveys the intended meaning.

Create a dynamic library.

As pointed out by Adam Borowski, static linking makes updates tedious.
This patch switches the package over to create a dynamic library
instead.

We have to specify -fPIC for compiling and --shared for linking. The
shared object is called liblopsub.so.X.Y.Z, where X, Y, and Z are
the digits of the version string as created from the git revision by
the version-gen.sh script. The soname for the linker to put into each
executable which is linked against lopsub is liblopsub.so.$X.

The install target is modified to install liblopsub.so.X.Y.Z instead
of liblopsub.a, and it also creates the usual symbolic links for
shared libraries. It does not run ldconfig, though.

Requested-by: Adam Borowski <kilobyte@angband.pl>

lopsub.7: Move installation instructions from man page to README.

As pointed out by Adam Borowski, installation instructions don't
really belong in the man page. This commit converts the instructions
from roff format to plain text which is added at the bottom of the
existing README file.

We keep the link to the git repository though, and add a few more
links to related resources.

Requested-by: Adam Borowski <kilobyte@angband.pl>

lopsub.7: Add NAME section.

Lintian complains about this because the NAME sections of all man
pages are parsed to generate the index for apropos(1) and co.

Each manual page should start with a "NAME" section, which lists the
name and a brief description of the page separated by "\-". The "NAME"
section is parsed by lexgrog and used to generate a database that's
queried by commands like apropos and whatis. This tag indicates that
lexgrog was unable to parse the NAME section of this manual page.

Improve diagnostics of lls_check_arg_count().

The old code could return an error message like

at least 1 non-option args required, 0 given

even if exactly 1 arg is required. So check this case and print

exactly 1 non-option args required, 0 given

instead. The check for the upper bound has the same issue. It is
considered a bug in the application if min_argc > max_argc, so check
for this case as well.

build: Honor the Filesystem Hierarchy Standard.

According to this standard, man pages should go to /usr/share/man
rather than to /usr/man.

build: Compress man pages.

Man pages should always be installed in compressed form, so run gzip
on all four man pages. We always specify -f so that gzip won't ask
questions, and use the highest compression level because the pages
are compressed only once and decompressed every time the man page
is opened.

build: .a files do not need to be executable.

We currently install liblopsub.a with mode 755, but the executable
bit is not needed. In fact, lintian complains about this.

build: Support DESTDIR.

It's strongly recommended to support this feature because it eases
packaging. And it's easy to implement.

build: Provide target distclean.

All software packages should at least provide the "clean" and "distclean"
targets. So far we only supported the former, which removed all generated
files.

This commit adds the distclean target and modifies the clean target
to only remove files generated by the compiler, but not the files
that were generated by lopsubgen.

build: Activate ONESHELL.

This instructs "make" to pass all the lines in the recipe to a single
invocation of the shell, which is generally a good idea since it
speeds up the build a bit.

lls_parse_arg(): Don't free static memory.

If opt->values is not NULL, no string value is stored on the heap,
and the current code results is a segmentation fault.

Add link to homepage.

It's OK to only link to the home page as the lopsub project page is
linked there.

add paragraph about required

config_file.l: Make the scanner reentrant.

This replaces the three global variables by a structure and modifies
lls_convert_config() to call yylex_init_extra() instead of yy_init()
to make a reference to the structure available to the actions.

config_file.l: Instruct flex to create a reentrant scanner.

This requires some modifications:

* Most functions take an additional yyscan_t argument.
* We must call yylex_init and yylex_destroy().
* Accessor methods must be used to get yytext and yylen.

We used to set the initial start condition in lls_convert_config(),
before the call to yylex(). For reentrant scanners, however,
the BEGIN macro can not be used in the user code section where
lls_convert_config() is located. But pushing a state works and should
be equivalent.

The generated scanner is not reentrant yet because it still has global
variables. This issue will be addressed in a subsequent patch.

config_file.l: Move helper functions to user code section.

These functions refer to the global variables yytext and yylen.
Reentrant scanners need to use accessor methods instead of accessing
the global variables directly. But these methods are not available
in the definitions section.

As a preparation for making the scanner reentrant, this patch moves
the three helper functions from the definitions section to the user
code section. Since the functions are called from the actions of the
pattern rules, we need to provide forward declarations.

Pure code movement, no actual changes.

config_file.l: Change default prefix for global symbols.

Without this, applications which use flex for their own work might run
into problems due to duplicate symbols when linking against liblopsub.
Since this is an ABI change, we have to increment the ABI version
number.

No changes in the source code are necessary since flex provides macros
which allow to still refer to the variables and functions with the
usual yy prefixed names. However, the command

nm -e liblopsub.a

shows that the external symbols are now prefixed with lls_yy.

Note that the patch only changes config_file.l. We don't bother to
adjust lopsubgen.l in the same way because the object file which
is derived from lopsubgen.l is not part of the library. It is only
linked into the lopsubgen executable.

version-gen.sh: Make it work in conflicted state.

If the working tree contains unmerged paths, git update-index -q
prints a "file: needs merge" message to stdout. This message confuses
the build system which runs this git command via version-gen.sh and
expects it to output a git version string.

This commit redirects stdout of the git command to /dev/null to make
sure that version-gen.sh outputs only the version string.

Fix bad grammar "allows <infinitive>".

In standard English, the verb "allows" can never take an infinitive as
its direct object.

lopsub.c: Fix a NULL pointer dereference and a double free.

The error path of lls_deserialize_parse_result() has two issues:

* if the allocation of lor->value fails, we dereference a NULL pointer
in the cleanup part after label free_options because in

free(lor->value[j].string_val);

lor->value is NULL.

* if the strdup() for a multiple option fails in the inner loop, we
deallocate all previously allocated strings, jump to the free_options
label, and attempt to free the same values again.

The root of both bugs is that we start the cleanup in the error case
using the current value of the outer loop index i. The fix is to
perform cleanup of the allocated memory for option i already in the
allocation loop and let the cleanup loop iterate downwards from i - 1.

This bug was found by the clang static analyzer.

Avoid warning about yywrap being redefined.

The flex documentation says

If you do not supply your own version of 'yywrap()', then you must
either use '%option noyywrap' (in which case the scanner behaves as
though 'yywrap()' returned 1), or you must link with '-lfl' to obtain
the default version of the routine, which always returns 1.

Unfortunately, if noyywrap is given, gcc-5.4.0 complains with

config_file.c:417:0: warning: "yywrap" redefined

 ^
config_file.c:74:0: note: this is the location of the previous definition

Just provide our own yywrap() to silence the warning.

The long option parser for subcommands (lopsub).

This library was under development for over a year and is now ready
for prime time. The code is believed to be mature and no bugs are
known at this time. The API is fully documented and stable, and no
new features are planned. Future fixes and enhancements will take
backwards compatibility into account.

The code used to be part of the paraslash package, but has been
moved to its own repository. All prior commits have been discarded,
so this repository contains only the final result as a single commit.

The input files for the lopsubgen utility and the config file parser
are based on flex. The API documentation is created with gendoc.m4,
a simple m4 file which is part of this repository.

Documentation includes the three man pages lopsub.7, lopsubgen.1 and
lopsub.suite.5 which describe different aspects of the library. There
is also an example application called lopsubex which illustrates
various features of the library.