Added DEVELOPERS.md.
This commit is contained in:
Andrew Wood
@@ -16,6 +16,8 @@ or "`man pv`" after installation.
|
||||
|
||||
Changes are listed in "[doc/NEWS.md](./doc/NEWS.md)". The to-do list is "[doc/TODO.md](./doc/TODO.md)".
|
||||
|
||||
Developers and translators, please see "[doc/DEVELOPERS.md](./doc/DEVELOPERS.md)".
|
||||
|
||||
|
||||
Compilation
|
||||
-----------
|
||||
@@ -29,14 +31,6 @@ systems, so if typing "`make`" gives an error, try "`gmake`" instead.
|
||||
|
||||
See the file "[doc/INSTALL](./doc/INSTALL)" for more about the _configure_ script.
|
||||
|
||||
Developers note that you can run "`./configure --enable-debugging`" to cause
|
||||
debugging support to be built in, and the `--enable-profiling` option builds
|
||||
in profiling support (see "`man gprof`"). Also note that running
|
||||
"`make index`" will generate an HTML code index (using _ctags_ and
|
||||
_cproto_); this index lists all files used, all functions defined, and all
|
||||
TODOs marked in the code. Finally, "`make analyse`" will run the "`splint`"
|
||||
and "`flawfinder`" tools on all C files to generate analysis files ("`*.e`").
|
||||
|
||||
|
||||
Author and acknowledgements
|
||||
---------------------------
|
||||
|
||||
@@ -0,0 +1,125 @@
|
||||
Notes for developers and translators
|
||||
====================================
|
||||
|
||||
The following "`configure`" options will be of interest to developers and
|
||||
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
|
||||
|
||||
|
||||
Debugging and profiling support
|
||||
-------------------------------
|
||||
|
||||
When "`./configure --enable-debugging`" is used, the "`pv`" produced by
|
||||
"`make`" will support an extra option, "`--debug FILE`", which will cause
|
||||
debugging output to be written to *FILE*. This is not recommended for
|
||||
production builds due to the extra processing it introduces, and the
|
||||
potential size of the output.
|
||||
|
||||
Within the code, "`debug()`" is used in a similar way to "`printf()`". It
|
||||
will automatically include the calling function, source file, and line
|
||||
number, so they don't need to be included in the parameters. When debugging
|
||||
support is not enabled, it evaluates to a null statement.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Source code analysis
|
||||
--------------------
|
||||
|
||||
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.
|
||||
|
||||
The eventual goal is for all C source files to generate zero warnings from
|
||||
either tool.
|
||||
|
||||
|
||||
Translation notes
|
||||
-----------------
|
||||
|
||||
The message catalogues used to translate program messages into other
|
||||
languages are in the "`src/nls/`" 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:
|
||||
|
||||
#: src/pv/cursor.c:85
|
||||
msgid "failed to get terminal name"
|
||||
msgstr "erro ao ler o nome do terminal"
|
||||
|
||||
The comment line, starting "`#`", shows the source filename and line number
|
||||
at which this message can be found. The "`msgid`" is the original message
|
||||
in the program, in English. The "`msgstr`" is the translated text.
|
||||
|
||||
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.
|
||||
|
||||
This means that after making a change to a "`.po`" file, do this:
|
||||
|
||||
make
|
||||
LANG=de LC_ALL=en_GB.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.
|
||||
|
||||
To add a new language, edit "`autoconf/configure.in`". Look for this line:
|
||||
|
||||
for lang in de fr pl pt; do
|
||||
|
||||
Add the new language code before the "`; do`".
|
||||
|
||||
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
|
||||
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.
|
||||
Reference in New Issue
Block a user