---

2.4 Configuring ¶

In interactive mode, or when given the -V option (the default when running Asymptote on a single file under MSDOS), Asymptote will automatically invoke your PostScript viewer (evince under UNIX) to display graphical output. The PostScript viewer should be capable of automatically redrawing whenever the output file is updated. The UNIX PostScript viewer gv supports this (via a SIGHUP signal). Users of ggv will need to enable Watch file under Edit/PostScript Viewer Preferences.

Configuration variables are most easily set as Asymptote variables in an optional configuration file config.asy (see configuration file). For example, the setting pdfviewer specifies the location of the PDF viewer. Here are the default values of several important configuration variables under UNIX:

import settings;
pdfviewer="acroread";
htmlviewer="google-chrome";
psviewer="evince";
display="display";
animate="animate";
gs="gs";
libgs="";

Under MSDOS, the viewer settings htmlviewer, pdfviewer, psviewer, display, and animate default to the string cmd, requesting the application normally associated with each file type. The (installation-dependent) default values of gs and libgs are determined automatically from the Microsoft Windows registry. The gs setting specifies the location of the PostScript processor Ghostscript, available from https://www.ghostscript.com/.

The configuration variable htmlviewer specifies the browser to use to display 3D WebGL output. The default setting is google-chrome under UNIX and cmd under Microsoft Windows. Note that Internet Explorer does not support WebGL; Microsoft Windows users should set their default html browser to chrome or microsoft-edge. By default, 2D and 3D HTML images expand to the enclosing canvas; this can be disabled by setting the configuration variable absolute to true.

On UNIX systems, to support automatic document reloading of PDF files in Adobe Reader, we recommend copying the file reload.js from the Asymptote system directory (by default, /usr/local/share/asymptote under UNIX to ~/.adobe/Acrobat/x.x/JavaScripts/, where x.x represents the appropriate Adobe Reader version number. The automatic document reload feature must then be explicitly enabled by putting

import settings;
pdfreload=true;
pdfreloadOptions="-tempFile";

in the Asymptote configuration file. This reload feature is not useful under MSDOS since the document cannot be updated anyway on that operating system until it is first closed by Adobe Reader.

The configuration variable dir can be used to adjust the search path (see Search paths).

By default, Asymptote attempts to center the figure on the page, assuming that the paper type is letter. The default paper type may be changed to a4 with the configuration variable papertype. Alignment to other paper sizes can be obtained by setting the configuration variables paperwidth and paperheight.

These additional configuration variables normally do not require adjustment:

config
texpath
texcommand
dvips
dvisvgm
convert
asygl

Warnings (such as "unbounded" and "offaxis") may be enabled or disabled with the functions

warn(string s);
nowarn(string s);

or by directly modifying the string array settings.suppress, which lists all disabled warnings.

Configuration variables may also be set or overwritten with a command-line option:

asy -psviewer=evince -V venn

Alternatively, system environment versions of the above configuration variables may be set in the conventional way. The corresponding environment variable name is obtained by converting the configuration variable name to upper case and prepending ASYMPTOTE_: for example, to set the environment variable

ASYMPTOTE_PAPERTYPE="a4";

under Microsoft Windows XP:

1. Click on the Start button;
2. Right-click on My Computer;
3. Choose View system information;
4. Click the Advanced tab;
5. Click the Environment Variables button.