retawq Documentation
Compile-Time Configuration Options
Introduction
For configuring retawq before building the program ("compile-time
configuration"), both a "classical" Makefile and a more modern/portable
configure script are supported.
- classical Makefile - you can change the options manually in the
file Makefile using a text editor. The compile-time configuration option names
begin with "OPTION_".
- configure script - you can specify the compile-time configuration
options as command-line arguments for the configure script. The arguments begin
with "--enable-", "--disable-" or "--set-"; in the description below, the value
"1" usually corresponds to "enabled", "0" to "disabled". You can get a list of
all script options with "./configure --help".
The Options
- OPTION_TG / --set-tg=... - the text/graphics mode which should be
used for the user interface; the following modes are currently supported:
- curses - a general curses library (using include file <curses.h>,
linking with "-lcurses"); you should try this one if you can't build retawq
with the default (ncurses) mode, e.g. because the default (ncurses) library
isn't available on your computer
- ncurses - the GNU ncurses library (using
include file <ncurses.h>, linking with "-lncurses")
- bicurses - a built-in curses functionality for text terminals; this mode
doesn't yet support colors and mouse, and it will never support all possible
combinations of oddities of all existing terminals; if it doesn't work on your
terminal, use a real curses library (it has been tested with the terminal types
"linux", "screen" and "xterm-color" and seems to work with them); it might just
be useful if you don't have enough RAM or (floppy) disk space for a fully-blown
curses library. The terminal type must be given in the environment variable
TERM, as usual. You can provide the environment variable TERMINFO as the path
of a directory which contains the terminfo files, otherwise the standard path
"/usr/share/terminfo/" is used. The usual environment variables COLUMNS and
LINES are respected as explained for xcurses below.
- xcurses - a built-in xcurses functionality which opens a window in an X Window System environment and emulates a curses
library there. Please note that this mode is relatively slow due to the scroll
bar calculations; you might want to disable scroll bars with the run-time configuration option "scroll-bars" or the
keyboard command action "scroll-bars-flip". - The
usual environment variables COLUMNS and LINES are respected if both are given
and have a value of at least 30 resp. 10; please note that some shells
automatically reset these variables soon after they changed, so you should do
it all in one line like so if necessary: "export COLUMNS=42; export LINES=21;
retawq".
- curses:headerfilename:libraryname - for special curses
libraries; fictitious example: "curses:foocurses.h:barcurses" results in using
include file <foocurses.h>, linking with "-lbarcurses"
- OPTION_TEXTMODEMOUSE / --enable-textmodemouse - whether you want to
get support for a "text-mode mouse" like gpm on text terminals or the mouse
cursor in terminal emulators like xterm (default: 1); this allows you to
activate links (and HTML form elements) by clicking them with the mouse, which
is easier and faster than pressing the Cursor-down/up keys several times. It
depends on your curses library whether you can actually get this support - it's
currently only available if the library provides ncurses-like mouse support
(technobabble: detected by the presence of the C pre-processor symbol
NCURSES_MOUSE_VERSION).
- OPTION_I18N / --enable-i18n - retawq supports several natural
languages (currently English, French, German, Spanish and Brazilian
Portuguese). By default, it uses the English language. If you prefer another
supported language, set this option to "1" / use --enable-i18n, set the option
PATH_INSTALL_LOCALE / --path-locale=... to whatever is appropriate for your
computer, and say "make install" after "make". (See the file INSTALL for details.) retawq uses the "gettext"
functionality to implement this option; some computers have this in their
standard C library, others might require a separate library called "intl"; if
compilation fails, you might have to install such a library or to leave the
feature disabled.
- OPTION_CED / --set-ced=... - quality of character entity display;
retawq normally tries to print nice characters on the screen for special HTML
character entities like "à". If your terminal can only handle
seven-bit ASCII characters and shows garbage otherwise, set this to 0.
- OPTION_NEWS / --enable-news - whether the URL
schemes "news"/"nntp" for news-reading should be supported (default: 1)
- OPTION_COOKIES / --enable-cookies - whether cookies should be
supported ("HTTP state management"; default: 1). Cookies will only be stored
and sent for servers for which the run-time
configuration option "http-cookies" explicitly allows it.
- OPTION_LOCAL_CGI / --enable-local-cgi - whether the URL scheme "local-cgi" should be supported (default: 0);
local CGI scripts will only be executed as explicitly allowed with the run-time configuration option "local-cgi".
Security Note: if you enable this feature, retawq will be able to
execute external scripts; such "scripts" can be any kind of executable
programs, so it could also be "viruses" or other malicious software. To avoid
unwanted effects, please observe at least the following hints: 1. You should
make sure that nobody but you can change your config file; otherwise someone
might be able to allow the execution of malicious CGI scripts with the
local-cgi feature. So you should use a command like "chmod go-rwx config" or
"chmod go-rwx /home/your_home/.retawq/"... 2. You should also make sure
that nobody can put malicious scripts into allowed paths or manipulate existing
allowed scripts.
- OPTION_EXECEXT / --set-execext=... - whether the execution of
external commands should be allowed; if you'd like to execute shell commands
with the keyboard command "!", set this option to 1 and
set the run-time configuration option
"execext-shell" as appropriate for the shell program you want to use.
Security Note: if you enable this feature, retawq will be able to
execute external programs; most of the security information given in the
description of OPTION_LOCAL_CGI above applies here too, respectively. There's a
reason why this option has such an ugly name...
- OPTION_TLS / --set-tls=... - which variant of TLS/SSL should be supported (default: 0); this is used for
the URL schemes "https" and "ftps"
- OPTION_IPV6 / --enable-ipv6 - whether the "next generation" Internet
Protocol version IPv6 should be supported (default: 0); IPv6 will only work if
the libraries and operating system on your computer support it
- OPTION_THREADING / --set-threading=... - which kind of threading
model should be used (default: 1); 0 means that the whole program runs in a
single thread, so all DNS hostname lookups will "block" the whole program and
it will seem to hang, possibly for many seconds; 1 means that DNS hostname
lookups run in their own thread, using a pthreads library; 2 means that the
Linux-specific clone() syscall is used instead of pthreads.
You should use 0 only if necessary, e.g. if you build a "whole system on
one floppy disk" with a non-Linux system and don't have enough free space for a
pthreads library. In short: use 1 if at all possible.
- CC - the name of the C compiler which is installed on your system;
the default is "gcc", the
GNU compiler collection.
- CFLAGS - special flags (command-line arguments) for your C compiler;
it should not be necessary to change anything here, but anyway... For
information about possible flags, please read the documentation of your C
compiler.
- All the other configuration options in the classical Makefile should
stay as they are - most of the respective features have not yet been fully
implemented.
Minimizing retawq's Size
retawq is already a quite small browser. If you want to make the executable
program still smaller, e.g. as a tool for a boot/rescue disk or a "whole system
on one floppy disk" collection, this section shows how to shrink retawq's size
by disabling "all" compile-time options, including some internal options which
aren't documented elsewhere. If you actually need a feature, you should leave
the respective option enabled, of course. The minimization is shown with the
configure script here; you can get the same result by editing the "classical"
Makefile manually.
As a starting point, disable all officially documented options which are
enabled by default: "./configure --disable-textmodemouse --disable-news
--disable-cookies --set-threading=0 --set-ced=0". You could additionally use
"--set-tg=curses" (if that works for you) to disable some ncurses-specific
code. - The disabling of multi-threading has the additional benefit that no
pthreads library is necessary.
Now for the "dirty" part: open the file ".config" (which was generated by
the configure script) in a text editor, and do any or all of the following; in
parentheses: effect of the change.
- set CONFIG_ABOUT to 0 (no "about:" URLs besides "about:retawq" will be
supported); or set it to the sum (technobabble: the bit-wise "or") of the
following individual values to leave the respective URLs enabled: 1 for
"about:activity", 2 for "about:hostinfo", 4 for "about:ctconfig", 8 for
"about:help".
- set CONFIG_BLOAT to 0; CONFIG_BLOAT concerns miscellaneous small pieces in
various parts of the program which add some nice comfort but no "actual"
functionality; you can set it to the sum (technobabble: the bit-wise "or") of
the following individual values to leave the respective pieces enabled: 1: show
human-readable explanations of server status codes in the bottom line of the
screen; 2: display IP addresses in "Connecting to" messages and in
"about:hostinfo" documents; 4: handle the command-line
option "--help"; 8: show the full list of available options with the command-line option "--help"; 16: a color-related feature
which isn't yet useful anyway, just disable it; 32: handle scroll bars
(currently relevant for OPTION_TG=xcurses only); 64: handle the run-time configuration option "termwintitle"
- set CONFIG_FINGER to 0 (the finger protocol won't be supported)
- set CONFIG_FTP to 0 (the FTP protocol won't be supported)
- set CONFIG_FTPDIR to 0 (FTP directory listings will contain less
information)
- set CONFIG_JUMPS to 0 (the "jumps" (URL shortcuts) feature won't be
available)
- set CONFIG_KEYMAPS to 0 (keymaps won't be
configurable)
- set CONFIG_LOCALDIR to 0 (local directory listings will contain less
information, sorting can't be customized)
- set CONFIG_RTCONFIG to 0 (retawq won't read run-time configuration files)
- set CONFIG_SESSIONS to 0 (you won't be able to save/resume sessions)
- set CONFIG_USER_QUERY to 0 (the resource manager won't be able to ask you
interactively for any login username, password etc.; you'll have to provide
this information directly in the URL or in run-time
configuration options)
- set HAVE_UNAME to 0 (the run-time configuration
option "user-agent" won't have any effect)
- set OPTION_MENUS to 0 (no menus will be available; especially you can't
change the selections of HTML form <select> tags)
- add the line "#define DO_NOT_INLINE" (retawq might become slightly slower;
hardly noticeable)
Finally, say "make" to build the program. Let's have a look at the resulting
size, for example when building version 0.2.5 on the x86 platform, Linux kernel
2.2.x, libc GNU glibc 2.2.x, compiler GNU gcc 2.7.2.3:
- 76 KB - minimal (but OPTION_TG=ncurses)
- 109 KB - all "official" options disabled
- 127 KB - default configuration
- 153 KB - everything enabled (./configure --enable-i18n --enable-local-cgi
--enable-ipv6 --set-tls=1 --set-execext=1)
On my computer, minimal retawq is much smaller than the file viewer "less"
(which has about 90 KB after running "strip --strip-unneeded less"), so you
might even consider removing "less" from your "whole system on one floppy disk"
collection and doing something like "ln -s retawq less". Funny, isn't it?
Newer versions of gcc seem to generate much worse code than the good/bad old
2.7.2.3. For these, you might want to replace the compiler option "-O2" with
"-Os" in the Makefile.
This documentation file is part of version 0.2.5a of retawq, a network client created by
Arne Thomaßen. retawq is basically released under
certain versions of the GNU General Public License and WITHOUT ANY WARRANTY.
Copyright (C) 2001-2004 Arne Thomaßen.