Next: , Previous: Base modules, Up: Top


8 Options

Type asy -h to see the full list of command-line options supported by Asymptote:

Usage: ../asy [options] [file ...]

Options (negate by replacing - with -no): 

-V,-View              View output; command-line only
-a,-align C|B|T|Z     Center, Bottom, Top, or Zero page alignment [Center]
-autoimport string    Module to automatically import [""]
-autoplain            Enable automatic importing of plain [true]
-autorotate           Enable automatic PDF page rotation [false]
-batchMask            Mask fpu exceptions in batch mode [false]
-batchView            View output in batch mode [false]
-bw                   Convert all colors to black and white [false]
-cd directory         Set current directory; command-line only
-cmyk                 Convert rgb colors to cmyk [false]
-c,-command string    Command to autoexecute
-compact              Conserve memory at the expense of speed [false]
-d,-debug             Enable debugging messages [false]
-divisor n            Free space divisor for garbage collection [2]
-globalwrite          Allow write to other directory; command-line only [false]
-gray                 Convert all colors to grayscale [false]
-h,-help              Show summary of options; command-line only
-historylines n       Retain n lines of history [1000]
-inlinetex            Generate inline tex code [false]
-interactiveMask      Mask fpu exceptions in interactive mode [true]
-interactiveView      View output in interactive mode [true]
-interactiveWrite     Write expressions entered at the prompt to stdout [true]
-k,-keep              Keep intermediate files [false]
-keepaux              Keep intermediate LaTeX .aux files [false]
-level n              Postscript level [3]
-l,-listvariables     List available global functions and variables [false]
-localhistory         Use a local interactive history file [false]
-m,-mask              Mask fpu exceptions; command-line only
-multiline            Input code over multiple lines at the prompt [false]
-multipleView         View output from multiple batch-mode files [false]
-O,-offset pair       PostScript offset [(0,0)]
-f,-outformat format  Convert each output file to specified format
-o,-outname name      Alternative output name for first file
-p,-parseonly         Parse file [false]
-prompt string        Prompt ["> "]
-prompt2 string       Continuation prompt for multiline input [".."]
-rgb                  Convert cmyk colors to rgb [false]
-safe                 Disable system call; command-line only [true]
-scroll n             Scroll standard output n lines at a time [0]
-tabcompletion        Interactive prompt auto-completion [true]
-tex engine           TeX engine ("latex|pdflatex|tex|pdftex|none") ["latex"]
-s,-translate         Show translated virtual machine code [false]
-twice                Run LaTeX twice (to resolve references) [false]
-unsafe               Enable system call (=> global); command-line only [false]
-u,-user string       General purpose user string [""]
-v,-verbose           Increase verbosity level [0]
-version              Show version; command-line only
-wait                 Wait for child processes to finish before exiting [false]
-where                Show where listed variables are declared [false]
-xformat format       GUI deconstruction format ["png"]

All boolean options, except for -unsafe, -safe, and -help, can be negated by prepending no to the option name.

If no arguments are given, Asymptote runs in interactive mode (see Interactive mode). In this case, the default output file is out.eps.

If - is given as the file argument, Asymptote reads from standard input.

If multiple files are specified, they are treated as separate Asymptote runs.

If the string autoimport is nonempty, a module with this name is automatically imported for each run as the final step in loading module plain.

Default option values may be entered as Asymptote code in a configuration file named config.asy (or the file specified by the environment variable ASYMPTOTE_CONFIG or -config option). Asymptote will look for this file in its usual search path. Typically the configuration file is placed in the .asy directory in the user's home directory (%USERPROFILE%\.asy under MSDOS). Configuration variables are accessed using the long form of the option names:

import settings;
outformat="pdf";
batchView=false;
interactiveView=true;
batchMask=false;
interactiveMask=true;
Command-line options override these defaults. Most configuration variables may also be changed at runtime. The advanced configuration variables dvipsOptions and gsOptions allow specialized options to be passed as a string to dvips and gs, respectively.

If you insert

import plain;
settings.autoplain=true;
at the beginning of the configuration file, it can contain arbitrary Asymptote code.

The default output format is EPS for the (default) latex tex engine and PDF for the pdflatex tex engine. An alternative output format (without antialiasing) may be produced by using the -f format option. This supports any format supported by the ImageMagick convert program (version 6.2.4 or later recommended; an Invalid Parameter error message indicates that the MSDOS utility convert is being used instead of the one that comes with ImageMagick). To give specific options to the convert program, call convert manually. This example enables antialiasing and produces a tiff format at double the usual size:

asy -o - venn | convert -density 288x288 -geometry 100%x eps:- venn.tiff

If the option -unsafe is given, Asymptote runs in unsafe mode. This enables the int system(string s) call, allowing one to execute arbitrary shell commands. The default mode, -safe, disables this call.

A PostScript offset may be specified as a pair (in bp units) with the -O option:

asy -O 0,0 file
The default offset is zero. The default value of the page alignment setting align is Center.

The -c (command) option may be used to execute arbitrary Asymptote code on the command line as a string. It is not necessary to terminate the string with a semicolon. Multiple -c options are executed in the order they are given. For example

asy -c 2+2 -c "sin(1)" -c "size(100); draw(unitsquare)" 
produces the output
4
0.841470984807897
and draws a unitsquare of size 100.

The -u (user) option may be used to specify arbitrary Asymptote settings on the command line as a string. It is not necessary to terminate the string with a semicolon. Multiple -u options are executed in the order they are given. Command-line code like -u x=sqrt(2) can be executed within a module like this:

real x;
usersetting();
write(x);

When the -l (listvariables) option is used with file arguments, only global functions and variables defined in the specified file(s) are listed.

Additional debugging output is produced with each additional -v option:

-v
Display top-level module and final output file names.
-vv
Also display imported and included module names and final LaTeX and dvips processing information.
-vvv
Also output LaTeX bidirectional pipe diagnostics.
-vvvv
Also output knot guide solver diagnostics.
-vvvvv
Also output Asymptote traceback diagnostics.