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".

If you're confused by all those options, compile the program with the default configuration and work with it to get used to it first, e.g. as described in the user guide. If compiling with the default configuration fails, you might just have to set OPTION_TG to "curses" and/or OPTION_THREADING to 0.

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 the program 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 emulation 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 can be 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". (Cf. 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 "&agrave;". 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 are only 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 are only executed as explicitly allowed with the run-time configuration option "local-cgi".
  Security Note: if you enable this feature, retawq is 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 is 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 can 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 "block" the whole program and it seems to hang, possibly for many seconds; 1 means that DNS hostname lookups run in their own thread, using a pthreads (Posix threads) library; 2 means that the Linux-specific clone() syscall is used (via the standard C library) 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.
• OPTION_BIRTCFG / --enable-birtcfg - this is a rather special option which specifies whether a "built-in" run-time configuration shall be used in addition to (or instead of) external run-time configuration files; if you enable this, you must prepare the run-time configuration which shall be built into retawq by running "tool/birtcfg.pl filename"; the configuration file filename which shall be built into retawq must not contain any double-quote (") character, neither in the options nor in comments, because such a character would confuse the C compiler. The script tool/birtcfg.pl is a Perl script (sorry:-), so you need a Perl interpreter to run it; the script expects the interpreter at /usr/bin/perl. - The main advantage of a built-in run-time configuration is that you need not carry external configuration files around. A disadvantage is that the built-in configuration can't be changed without rebuilding the program, but you can disable it with the command-line option "--rtcfg=..." if necessary. To read the contents of a built-in configuration, visit the URL "about:birtcfg" in retawq.
• 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 configuration 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 on your computer) 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" are 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 message line; 2: show 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"; 32: handle scroll bars (currently relevant for OPTION_TG=xcurses only); 64: handle the run-time configuration option "termwintitle"; 256: support colors in general
• set CONFIG_CONSOLE to 0 (the console runmode isn't available)
• set CONFIG_EXTRA to 0; CONFIG_EXTRA concerns miscellaneous pieces in various parts of the program similiar to CONFIG_BLOAT, but regarding "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: all "download" functionality, e.g. the command-line option "--download" and the keyboard commands "D" and "ctrl-d"; 2: all "dump" functionality, e.g. the command-line option "--dump" and the keyboard command "d"
• set CONFIG_FINGER to 0 (the finger protocol isn't supported)
• set CONFIG_FTP to 0 (the FTP protocol isn't supported)
• set CONFIG_FTPDIR to 0 (FTP directory listings contain less information)
• set CONFIG_HTTP to 0; CONFIG_HTTP concerns several special HTTP-related features; you can set it to the sum (technobabble: the bit-wise "or") of the following individual values to leave the respective features enabled: 1: support for HTTP/1.1 (otherwise, only HTTP/1.0 is supported); 16: HTTP proxy authentication (cf. the run-time configuration options "http-proxies" and "https-proxies")
• set CONFIG_JUMPS to 0 (the "jumps" (URL shortcuts) feature isn't available)
• set CONFIG_KEYMAPS to 0 (keymaps aren't configurable)
• set CONFIG_LOCALDIR to 0 (local directory listings contain less information, sorting can't be customized)
• set CONFIG_MENUS to 0 (no menus are available; especially you can't change the selections of HTML form <select> tags); or set it to the sum (technobabble: the bit-wise "or") of the following individual values to leave the respective menu-related features enabled: 1: contextual menu (e.g. keyboard command "m"); 2: URL history menu (keyboard command "u"); 4: window list menu (keyboard command "ctrl-w"); 8: menu for changing the selections of HTML form <select> tags
• set CONFIG_RTCONFIG to 0 (retawq doesn't handle run-time configuration, neither a built-in string nor an external file)
• set CONFIG_SESSIONS to 0 (you can't save/resume sessions)
• set CONFIG_USER_QUERY to 0 (the resource manager can't ask you interactively for any login username, password etc.; you have to provide such information directly in the URL or in run-time configuration options)
• set CONFIG_WK to 0 (no window kind besides "browser window" is available; especially, the kind "information window" is disabled)
• set HAVE_UNAME to 0 (the number for the run-time configuration option "user-agent" doesn't have any effect)
• 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 some resulting sizes, for example when building version 0.2.6 on the x86 platform, Linux kernel 2.2.x, libc GNU glibc 2.2.x, compiler GNU gcc 2.7.2.3:

• 74 KB - minimal (but OPTION_TG=ncurses)
• 129 KB - all "official" options disabled
• 147 KB - default configuration
• 177 KB - everything enabled (./configure --enable-i18n --enable-local-cgi --enable-ipv6 --set-tls=1 --set-execext=1) except "--enable-birtcfg"

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.