// vim:set filetype=asciidoc:
[[tips]]
== Tips

Please also read insightful pages linked from "`https://www.eyrie.org/~eagle/notes/debian/[Notes on Debian]`" by Russ Allbery (long time Debian developer) which have best practices for advanced packaging topics.

// [[multibinary]]
// === Building with multiple build conditions
//
// You can build several binary packages with several different build conditions. E.g.:
//
// * Add binary package stanzas for all generated binary packages in *debian/control* file.
// * Add *override_dh_auto_configure* target in the **debian/rules/*** file for making multiple copies of the upstream source and invoking multiple "`**dh_auto_configure -D ...**`" commands.
// * Add *override_dh_auto_build* target in the **debian/rules/*** file for invoking multiple "`**dh_auto_build -D ...**`" commands
// * Add *override_dh_auto_install* target in the **debian/rules/*** file for invoking multiple "`**dh_auto_install -D ...**`" commands
//
// [[udeb]]
// === Building *udeb* package
//
// You can build *udeb* packages with "`**Package-Type: udeb**`" set in *debian/control* (see "`https://www.debian.org/doc/debian-policy/ch-controlfields.html#package-type[Package-Type]`").

[[utf-8-build]]
=== Build under UTF-8

The default locale of the build environment is *C*.

Some programs such as the *read* function of Python3 change their behavior depending on the locale.

Adding the following code to the *debian/rules* file ensures building the program under the *C.UTF-8* locale.

----
LC_ALL := C.UTF-8
export LC_ALL
----

[[utf-8-conv]]
=== UTF-8 conversion

If upstream documents are encoded in old encoding schemes, converting them to https://en.wikipedia.org/wiki/UTF-8[UTF-8] is a good idea.

Use the *iconv* command in the *libc-bin* package to convert the encoding of plain text files.

----
 $ iconv -f latin1 -t utf8 foo_in.txt > foo_out.txt
----

Use *w3m*(1) to convert from HTML files to UTF-8 plain text files. When you do this, make sure to execute it under UTF-8 locale.
----
 $ LC_ALL=C.UTF-8 w3m -o display_charset=UTF-8 \
        -cols 70 -dump -no-graph -T text/html \
        < foo_in.html > foo_out.txt
----

Run these scripts in the *override_dh_** target of the *debian/rules* file.


[[debug]]
=== Hints for Debugging

When you face build problems or core dumps of generated binary programs, you need to resolve them yourself.  That's *debug*.

This is too deep a topic to describe here.  So, let me just list few pointers and hints for some typical debug tools.

* Wikipedia: "`https://en.wikipedia.org/wiki/Core_dump[core dump]`"
** "`*man core*`"
** Update the "`*/etc/security/limits.conf*`" file to include the following:
+
-------
* soft core unlimited
-------
** "`*ulimit -c unlimited*`" in *~/.bashrc*
** "`*ulimit -a*`" to check
** Press *Ctrl-\* or "`*kill -ABRT* 'PID'`" to make a core dump file
* *gdb* - The GNU Debugger
** "`*info gdb*`"
** "`Debugging with GDB`" in */usr/share/doc/gdb-doc/html/gdb/index.html*
* *strace* - Trace system calls and signals
** Use *strace-graph* script found in */usr/share/doc/strace/examples/* to make a nice tree view
** "`*man strace*`"
* *ltrace* - Trace library calls
** "`*man ltrace*`"
* "`*sh -n* __script.sh__`" - Syntax check of a Shell script
* "`*sh -x* __script.sh__`" - Trace a Shell script
* "`*python3 -m py_compile* __script.py__`" - Syntax check of a Python script
* "`*python3 -mtrace --trace* __script.py__`" - Trace a Python script
* "`*perl -I ../libpath -c* __script.pl__`" - Syntax check of a Perl script
* "`*perl -d:Trace* __script.pl__`" - Trace a Perl script
** Install the *libterm-readline-gnu-perl* package or its equivalent to add input line editing capability with history support.
* *lsof* - List open files by processes
** "`*man lsof*`"

TIP: The *script* command records console outputs.

TIP: The *screen* and *tmux* commands used with the *ssh* command offer secure and robust remote connection terminals.

TIP: A Python- and Shell-like REPL (=READ + EVAL + PRINT + LOOP) environment for Perl is offered by the *reply* command from the *libreply-perl* (new) package and the *re.pl* command from the *libdevel-repl-perl* (old) package.

TIP: The *rlwrap* and *rlfe* commands add input line editing capability with history support to any interactive commands.  E.g. "`*rlwrap dash -i*'`" .
