Major restructuring to switch build system from old scripts to GNU Automake.

This commit is contained in:
Andrew Wood
2023-08-28 10:04:39 +01:00
parent 5495e0e808
commit e99548ea8a
90 changed files with 1704 additions and 3521 deletions
+24 -47
View File
@@ -6,12 +6,9 @@ translators:
* `--enable-debugging` - build in debugging support
* `--enable-profiling` - build in support for profiling
* `--enable-static-nls` - compile translations directly into the program
These "`make`" targets are available:
* `make help` - describe all of the "`.PHONY`" targets
* `make index` - generate a source code index
* `make analyse` - run _splint_ and _flawfinder_ on all C source files
@@ -33,24 +30,8 @@ This does mean that if you call "`debug()`", make sure it has no side
effects, as they won't be present in builds without debugging support.
Builds produced after "`./configure --enable-profiling`" will write profile
data when run, to be used with _gprof_. See "`man gprof`" for details.
Source code indexing
--------------------
Running "`make index`" calls a script which uses _cproto_ and _ctags_ to
generate a single file, "`index.html`", which lists all C source files, all
functions within them, and all TODOs marked in the code.
It relies on each function having a comment block directly before it,
describing what it does.
The indexing script pre-dates the author's knowledge of documentation
generation tools like Doxygen, and is over 20 years old. If it contains
bugs, then rather than fixing them, it may be worth looking at how to alter
the C sources to better suit widely available documentation generation
tools. Please open issues or start discussions about this if it comes up.
data when run, to be used with _gprof_. See "`man gprof`" for details.
Please note that the memory safety checks will fail with profiling enabled.
Source code analysis
@@ -60,9 +41,9 @@ Running "`make analyse`" runs _splint_ and _flawfinder_ on all C sources,
writing the output of both programs to files named "`*.e`" for each "`*.c`".
There are no dependency rules set up for these "`.e`" files, so if a header
file is altered, either run "`make analysisclean`", manually remove the
relevant "`.e`" files, or update the timestamp of the relevant "`.c`" files
before running "`make analyse`" again.
file is altered, manually remove the relevant "`.e`" files, or update the
timestamp of the relevant "`.c`" files, before running "`make analyse`"
again.
The eventual goal is for all C source files to generate zero warnings from
either tool.
@@ -72,7 +53,7 @@ Translation notes
-----------------
The message catalogues used to translate program messages into other
languages are in the "`src/nls/`" directory, named "`xx.po`", where "`xx`"
languages are in the "`po/`" directory, named "`xx.po`", where "`xx`"
is the ISO 639-1 2-letter language code, such as "`fr`" for French.
Each of these files contains lines like this:
@@ -89,37 +70,33 @@ It is the "`msgstr`" lines which need to be updated by translators.
Message catalogue files should all be encoded as UTF-8.
To quickly test translations, use "`./configure --enable-static-nls`". This
is not recommended for production use, because it replaces the system
internationalisation libraries with some very simplistic alternatives, but
it has the benefit of compiling the message catalogues directly into the
program.
_FIXME: The test below doesn't work on Debian with only en_GB installed, and
also it looks like the compiled-in LOCALEDIR is overriding LOCPATH._
This means that after making a change to a "`.po`" file, do this:
After making a change to a "`.po`" file, test it by compiling it and installing
to a temporary location, like this:
make
LANG=de LC_ALL=en_GB.UTF-8 ./pv --help
make install DESTDIR=/tmp/yourtest
localedef -f UTF-8 -i de_DE /tmp/yourtest/usr/local/share/locale/de_DE.UTF-8
LOCPATH=/tmp/yourtest/usr/local/share/locale \
LC_ALL=de_DE.UTF-8 ./pv --help
Replace "`--help`" with whatever is appropriate for your test. In this
example, the language being tested is "`de`" (German), on a system which is
otherwise running in English with UTF-8 support.
running with UTF-8 support.
To add a new language, edit "`autoconf/configure.in`". Look for this line:
To add a new language, create the new message catalogue file under "`po/`"
by copying "`po/pv.pot`" to "`po/xx.po`", where "`xx`" is the language code,
and adjusting it. The "`.pot`" file is generated automatically by "`make`".
for lang in de fr pl pt; do
Next, add the language code to "`po/LINGUAS`" - this is a list of the
2-letter codes of the supported languages.
Add the new language code before the "`; do`".
Finally, run "`./config.status`" and "`make -C po update-po`".
Create the new message catalogue file under "`src/nls/`" by copying
"`src/nls/pv.pot`" to "`src/nls/xx.po`", where "`xx`" is the language code,
and adjusting it.
Then run "`./generate.sh`" to generate a new "`configure`" script; you will
need to run "`./configure --enable-static-nls`" and "`make`" afterwards.
When the source code is updated, running "`make`" will update the "`pv.pot`"
file so that it lists where all the messages are in the source, and running
"`make update-po`" will use _msgmerge_ to update all of the "`.po`" files
When the source code is updated, running "`make -C po update-po`" will
update the "`pv.pot`" file so that it lists where all the messages are in
the source. It will also use _msgmerge_ to update all of the "`.po`" files
from the updated "`pv.pot`" file. After doing this, look for missing
translations (empty "`msgstr`" lines) or translations marked as "fuzzy", as
these will need to be corrected by translators.
+12 -6
View File
@@ -1,13 +1,19 @@
0.0.20230816-UNRELEASED
0.0.20230828-UNRELEASED
* feature: new "`--enable-static`" option to "`configure`" for static builds ([#75](https://codeberg.org/a-j-wood/pv/pull/75))
* cleanup: added a test for terminal width detection to "`make test`"
* cleanup: added a test to "`make test`" to ensure that "`make install`" installs everything expected
* security: with "`--pidfile`", write to a temporary file and rename it into place, to improve security
* security: keep self-contained copies of name and format string in PV internal state for memory safety
* cleanup: switched the build system to GNU Automake
* cleanup: added a test for terminal width detection to "`make check`"
* cleanup: added a test to "`make check`" to ensure that "`make install`" installs everything expected
* cleanup: replaced *AC_HEADER_TIOCGWINSZ* with *AC_CHECK_HEADERS(sys/ioctl.h)* for better MacOS compatibility ([#74](https://codeberg.org/a-j-wood/pv/issues/74))
* cleanup: with "`--sync`", call `fsync()` instead of `fdatasync()` on incapable systems ([#73](https://codeberg.org/a-j-wood/pv/issues/73))
* cleanup: keep self-contained copies of name and format string in PV internal state for memory safety
* cleanup: with "`--pidfile`", write to a temporary file and rename it into place, to improve security
* misc: moved from GitHub to Codeberg; updated issue tracking links in documentation
* cleanup: replaced the test harness with the one native to GNU Automake
* cleanup: the manual is now a static file instead of needing to be built with "`configure`"
* dropped: dropped support for "`--enable-static-nls`"
* dropped: removed the Linux Software Map file, as the LSM project appears to be long dead
* dropped: will no longer publish to SourceForge as it has a chequered history and is unnecessary
* dropped: removed project from GitHub and moved to Codeberg - see "[Give Up GitHub](https://giveupgithub.org/)"
1.7.24 - 30 July 2023
-1
View File
@@ -1 +0,0 @@
pv
-4
View File
@@ -41,10 +41,6 @@ Feature requests
* ([#54](https://codeberg.org/a-j-wood/pv/issues/54)) Run command every n percent ([haarp](https://github.com/haarp))
* ([#56](https://codeberg.org/a-j-wood/pv/issues/56)) Support for backgrounding pv, and allowing it to be monitored separately ([jimbobmcgee](https://github.com/jimbobmcgee))
* ([#67](https://codeberg.org/a-j-wood/pv/issues/67)) Wrap another process to monitor its stdin & stdout ([Alex Mason](https://github.com/axman6))
* Make the manual a static file instead of building it with "configure"
* Drop support for the LSM as the LSM project appears to be dead
* Drop SourceForge from the release checklist as it has been problematic for OSS for decades
* Switch build system to GNU Automake
* Switch license to GPLv3+
Any assistance would be appreciated.
-1
View File
@@ -1 +0,0 @@
0.0.20230816-UNRELEASED
+39
View File
@@ -0,0 +1,39 @@
#!/bin/bash
#
# Benchmark the read/write performance of pv by looking at the number of
# read() and write() calls and the average amount of data transferred each
# time, as suggested by Ville Herva <Ville.Herva@iki.fi>.
#
test_input=$(mktemp /tmp/pvbench1XXXXXX)
strace_output=$(mktemp /tmp/pvbench2XXXXXX)
trap 'rm -f ${test_input} ${strace_output}' EXIT
pv=${pv:-./pv}
test -x "${pv}" || pv="pv"
dd if=/dev/zero of="${test_input}" bs=1k count=1k >/dev/null 2>&1
echo -e "Buf(k)\tRate(k)\tReads\tRsize\tWrites\tWsize"
for ((buffer=100; buffer<=1000; buffer+=100)); do
for ((rate=100; rate<=1000; rate+=100)); do
rateparm="-L ${rate}k"
test ${rate} -eq 0 && rateparm=""
strace -tt -o "${strace_output}" \
"${pv}" "${rateparm}" -B "${buffer}k" \
-f < "${test_input}" > /dev/null 2>&1
rdata=$(
awk '$2~/^read\(0,/{c++;t+=$NF}END{print c "\t" t/c}' \
"${strace_output}"
)
wdata=$(
awk '$2~/^write\(1,/{c++;t+=$NF}END{print c "\t" t/c}' \
"${strace_output}"
)
echo -e "${buffer}\t${rate}\t${rdata}\t${wdata}"
done
done
# EOF
-19
View File
@@ -1,19 +0,0 @@
Begin3
Title: @PACKAGE@
Version: @VERSION@
Entered-date: 30JUL23
Description: A tool for monitoring the progress of data through a
pipeline. It can be inserted into any normal pipeline
between two processes to give a visual indication of how
quickly data is passing through, how long it has taken, how
near to completion it is, and an estimate of how long it
will be until completion.
Keywords: progress bar, console, pipe, transfer rate
Author: Andrew Wood <andrew.wood@ivarch.com>
Maintained-by: Andrew Wood <andrew.wood@ivarch.com>
Primary-site: http://www.ivarch.com/programs/@PACKAGE@.shtml
Alternate-site:
Original-site:
Platforms:
Copying-policy: Artistic 2.0
End
+41 -41
View File
@@ -1,17 +1,17 @@
.TH @UCPACKAGE@ 1 "August 2023" Linux "User Manuals"
.TH PV 1 "August 2023" Linux "User Manuals"
.SH NAME
@PACKAGE@ \- monitor the progress of data through a pipe
pv \- monitor the progress of data through a pipe
.SH SYNOPSIS
.B @PACKAGE@
.B pv
[\fIOPTION\fR]
[\fIFILE\fR]...
.br
.B @PACKAGE@
.B pv
[\fI\-h\fR|\fI\-V\fR]
.SH DESCRIPTION
.B @PACKAGE@
.B pv
shows the progress of data through a pipeline by giving information such as
time elapsed, percentage completed (with progress bar), current throughput
rate, total data transferred, and ETA.
@@ -20,7 +20,7 @@ To use it, insert it in a pipeline between two processes, with the
appropriate options. Its standard input will be passed through to its
standard output and progress will be shown on standard error.
.B @PACKAGE@
.B pv
will copy each supplied
.B FILE
in turn to standard output
@@ -35,15 +35,15 @@ A simple example to watch how quickly a file is transferred using
.BR nc (1):
.RS
.B @PACKAGE@ file | nc -w 1 somewhere.com 3000
.B pv file | nc -w 1 somewhere.com 3000
.RE
A similar example, transferring a file from another process and passing the
expected size to
.BR @PACKAGE@ :
.BR pv :
.RS
.B cat file | @PACKAGE@ -s 12345 | nc -w 1 somewhere.com 3000
.B cat file | pv -s 12345 | nc -w 1 somewhere.com 3000
.RE
A more complicated example using numeric output to feed into the
@@ -53,7 +53,7 @@ program for a full-screen progress display:
.RS
.B (tar cf - . \e
.br
.B " | @PACKAGE@ -n -s $(du -sb . | awk '{print $1}') \e"
.B " | pv -n -s $(du -sb . | awk '{print $1}') \e"
.br
.B " | gzip -9 > out.tgz) 2>&1 \e"
.br
@@ -63,24 +63,24 @@ program for a full-screen progress display:
Taking an image of a disk, skipping errors:
.RS
.B @PACKAGE@ -EE /dev/your/disk/device > disk-image.img
.B pv -EE /dev/your/disk/device > disk-image.img
.RE
Writing an image back to a disk:
.RS
.B @PACKAGE@ disk-image.img > /dev/your/disk/device
.B pv disk-image.img > /dev/your/disk/device
.RE
Zeroing a disk:
.RS
.B @PACKAGE@ < /dev/zero > /dev/your/disk/device
.B pv < /dev/zero > /dev/your/disk/device
.RE
Note that if the input size cannot be calculated, and the output is a block
device, then the size of the block device will be used and
.B @PACKAGE@
.B pv
will automatically stop at that size as if
.B \-S
had been given.
@@ -88,25 +88,25 @@ had been given.
(Linux only): Watching file descriptor 3 opened by another process 1234:
.RS
.B @PACKAGE@ -d 1234:3
.B pv -d 1234:3
.RE
(Linux only): Watching all file descriptors used by process 1234:
.RS
.B @PACKAGE@ -d 1234
.B pv -d 1234
.RE
.SH OPTIONS
.B @PACKAGE@
.B pv
takes many options, which are divided into display switches, output
modifiers, and general options.
.SH DISPLAY SWITCHES
If no display switches are specified,
.B @PACKAGE@
.B pv
behaves as if
.BR \-p ", " \-t ", " \-e ", " \-r ", and " \-b
had been given (i.e. everything except average rate is switched on).
@@ -123,7 +123,7 @@ moving.
.TP
.B \-t, \-\-timer
Turn the timer on. This will display the total elapsed time that
.B @PACKAGE@
.B pv
has been running for.
.TP
.B \-e, \-\-eta
@@ -191,7 +191,7 @@ section below.
.TP
.B \-n, \-\-numeric
Numeric output. Instead of giving a visual indication of progress,
.B @PACKAGE@
.B pv
will give an integer percentage, one per line, on standard error, suitable
for piping (via convoluted redirection) into
.BR dialog (1).
@@ -313,7 +313,7 @@ parts of it apart.
.TP
.B \-f, \-\-force
Force output. Normally,
.B @PACKAGE@
.B pv
will not output any visual display if standard error is not a terminal.
This option forces it to do so.
.TP
@@ -322,7 +322,7 @@ Use cursor positioning escape sequences instead of just using carriage
returns. This is useful in conjunction with
.B \-N
(name) if you are using multiple
.B @PACKAGE@
.B pv
invocations in a single, long, pipeline.
@@ -410,7 +410,7 @@ the effect of caches, at the cost of performance. Due to memory alignment
requirements, it also may cause read or write failures with an error of
"Invalid argument", especially if reading and writing files across a variety
of filesystems in a single
.B @PACKAGE@
.B pv
call. Use this option with caution.
.TP
.B \-d PID[:FD], \-\-watchfd PID[:FD]
@@ -419,7 +419,7 @@ Instead of transferring data, watch file descriptor
of process
.BR PID ,
and show its progress. The
.B @PACKAGE@
.B pv
process will exit when
.B FD
either changes to a different file, changes read/write mode, or is closed;
@@ -431,7 +431,7 @@ If only a
.B PID
is specified, then that process will be watched, and all regular files and
block devices it opens will be shown with a progress bar. The
.B @PACKAGE@
.B pv
process will exit when process
.B PID
exits.
@@ -440,14 +440,14 @@ exits.
If
.B PID
is an instance of
.B @PACKAGE@
.B pv
that is already running,
.B \-R PID
will cause that instance to act as though it had been given
this instance's command line instead. For example, if
.B @PACKAGE@ -L 123K
.B pv -L 123K
is running with process ID 9876, then running
.B @PACKAGE@ -R 9876 -L 321K
.B pv -R 9876 -L 321K
will cause it to start using a rate limit of 321KiB instead of 123KiB.
Note that some options cannot be changed while running, such as
.BR \-c ,
@@ -462,15 +462,15 @@ and
.TP
.B \-P FILE, \-\-pidfile FILE
Save the process ID of
.B @PACKAGE@
.B pv
in
.BR FILE .
The file will be replaced if it already exists, and will be removed when
.B @PACKAGE@
.B pv
exits. While
.B @PACKAGE@
.B pv
is running, it will contain a single number - the process ID of
.B @PACKAGE@
.B pv
- followed by a newline.
.TP
.B \-h, \-\-help
@@ -556,19 +556,19 @@ The format string equivalent of turning on all display switches is
Some suggested common switch combinations:
.TP
.B @PACKAGE@ -ptebar
.B pv -ptebar
Show a progress bar, elapsed time, estimated completion time, byte counter,
average rate, and current rate.
.TP
.B @PACKAGE@ -betlap
.B pv -betlap
Show a progress bar, elapsed time, estimated completion time, line counter,
and average rate, counting lines instead of bytes.
.TP
.B @PACKAGE@ -t
.B pv -t
Show only the elapsed time - useful as a simple timer, e.g.
.BR "sleep 10m | pv -t" .
.TP
.B @PACKAGE@ -pterb
.B pv -pterb
The default behaviour: progress bar, elapsed time, estimated completion
time, current rate, and byte counter.
@@ -620,7 +620,7 @@ contributors.
.SH KNOWN PROBLEMS
The following problems are known to exist in
.BR @PACKAGE@ :
.BR pv :
.TP
.B *
In some versions of
@@ -644,7 +644,7 @@ running, if started near the bottom of the screen (IPC is needed to handle
the terminal scrolling). To fix this, start
.B cygserver
before using
.BR "@PACKAGE@ -c" .
.BR "pv -c" .
.P
.TP
.B *
@@ -655,7 +655,7 @@ option is not available on Cygwin without
running (SYSV IPC is needed). To fix this, start
.B cygserver
before running the instance of
.B @PACKAGE@
.B pv
you want, at runtime, to change the parameters of.
.P
If you find any other problems, please report them.
@@ -663,9 +663,9 @@ If you find any other problems, please report them.
.SH REPORTING BUGS
Report bugs in
.B @PACKAGE@
.B pv
to pv@ivarch.com or use the contact form linked from the
.B @PACKAGE@
.B pv
home page: <http://www.ivarch.com/programs/pv.shtml>
+3 -5
View File
@@ -1,18 +1,16 @@
Before releasing a new version, go through this checklist:
- check for patches from https://tracker.debian.org/pkg/pv
- bump doc/VERSION
- bump doc/lsm.in
- bump version in configure.ac and doc/NEWS.md
- check doc/NEWS.md is up to date
- check manual is up to date
- make indent; make indent indentclean
- make update-po
- make test
- make check
- commit to repository
- wipe build directory, re-run generate.sh and configure
- wipe build directory, re-run autoreconf and configure
- make release MAINTAINER=<signing-user>
- make manhtml | tidy -asxhtml | sed -e '1,/<body>/d' -e '/<\/body>/,$d'
- update HTML for todo and news
- copy and sign tar.gz to HTML directory (sig as both .asc and .txt)
- submit new release to Sourceforge
- upload HTML