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 shall be
used; the following modes are currently supported:
- curses - a general curses library (using include file <curses.h>,
linking with "-lcurses")
- ncurses - the GNU ncurses library (using
include file <ncurses.h>, linking with "-lncurses")
- xcurses - a built-in xcurses functionality which opens a window in an X Window System environment and emulates a curses
library there
- curses:headerfilename:libraryname - for special curses
variants; 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 some "text-mode mouse" like gpm on text consoles 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.)
- 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 if explicitly allowed in 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 shall 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 will be 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-ced=0". You could additionally use "--set-tg=curses"
(if that works for you) to disable some ncurses-specific code.
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_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 will become slightly
slower)
Finally, say "make" to build the program. Let's have a look at the resulting
size, for example when building version 0.2.0 on the x86 platform, Linux kernel
2.2.x, libc GNU glibc 2.2.x, compiler GNU gcc 2.7.2.3:
- 75 KB - minimal (but OPTION_TG=ncurses)
- 101 KB - all "official" options disabled
- 118 KB - default configuration
- 140 KB - everything enabled (using GnuTLS, not OpenSSL)
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?
You can reduce the "total" size even further by changing OPTION_THREADING so
that no pthreads library is necessary...
This documentation file is part of version 0.2.4 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.