User Tools

Site Tools


geda:gaf_utility

Translations: Русский

gaf - gEDA/gaf Command-Line Utility

gaf provides a number of small command-line utilities for working with schematic and symbol files, and is designed to be used for batch processing of designs created using the schematic editor gschem. It currently has three built-in commands:

  • gaf export is used to create SVG, PDF, PNG, PS and EPS files from schematic and symbol files, for printing or embedding in other documents.
  • gaf config allows reading and writing settings in gEDA project, user and system configuration stores.
  • gaf shell provides a Scheme REPL for command-line batch processing of schematic data.

See the gaf(1) manual page for more information on the utility options.

gaf export

The detailed description of the gaf export command can be found in the gaf(1) manual page.

gaf config

This section describes how to set up gschem and gnetlist using the gaf config command.

See the gaf(1) manual page for more information on the utility options.

Configuration files

Configuration settings used to configure these programs are written to gEDA config files. These files are:

  • geda-system.conf for system-wide settings. The system-wide config file is sequentially searched in three places:
    • in ${XDG_CONFIG_DIRS}/gEDA, see the XDG Base Directory Specification for more information on that environment variable,
    • if no system configuration was found there, in the traditional location of gEDA rc-files, i.e. in the ${PREFIX}/share/gEDA directory, where ${PREFIX} is a compiled default, usually /usr or /usr/local (but Debian based distributions use the /etc/gEDA directory instead),
    • and finally, if no configuration file was found yet, in an XDG default directory or, if it is not defined, in the /etc/xdg/gEDA directory.
  • $HOME/.gEDA/geda-user.conf for user settings.
  • path/to/a/project/geda.conf for your local project settings.

Note that you can edit these files manually using your favorite text editor.

The config file format is described in this freedesktop.org standard.

All the config files consist of sections, called groups, containing key-value pairs.

Key values in the gEDA config files may be single numbers or lists. Note that unlike the gaf export command, where several list separators can be used, the only separator between list values in the config files is semicolon ';'. Another difference is that, when using the gaf config command, you always have to specify all parameters of the used list. Thus, for example, the next command will not work properly:

gaf config --project export size 1000

The right command will look like this:

gaf config --project export size "1000;1000"

All sizes should be given in Adobe points (72 points = 1 inch). Suffixes such as “pt”, “mm” and others, which can be used with the gaf export command, do not work in the config files.

Next sections describe all existing groups.

export group

Table 1. export group parameters

Key Format Default
align string “auto” or list of two integers in the form HALIGN;VALIGN auto
dpi integer 96
font string Arial
layout predefined string: “portrait”, “landscape”, or “auto” auto
margins list of four integers in the form TOP;LEFT;BOTTOM;RIGHT 18;18;18;18
monochrome boolean true
paper predefined paper size string locale dependent
size string “auto” or list of two integers in the form HEIGHT;WIDTH auto

align

Set how the drawing is aligned within the page. HALIGN controls the horizontal alignment, and VALIGN the vertical. Each alignment value should be in the range 0.0 to 1.0. The “auto” alignment is equivalent to a value of 0.5:0.5, i.e. centered.

For gaf export command, you can use your locale's separator if you use it without quotes. In such a case your shell will interpret the numbers for you. You cannot do this for gaf config since the align key is a string. You must use a dot as the separator for floating point numbers when you write that string in a config file. See examples below.

dpi

Set the number of pixels per inch used when generating PNG output.

font

Set the font to be used for drawing text.

See the section Fonts below for more information on fonts selection.

layout

When using a paper size, set the orientation of the output. If “auto” layout is used, the orientation that best fits the drawing will be used.

margins

Set the widths of the margins to be used.

Margins can actually be wider than the values set in a config file since these values only specify the minimal distances from the sheet edges, and the sizes of the chosen paper may not meet the sizes of the printed schematic with the margins. If not specified, default margin size is 18pt for all margins.

Note: setting less than four numbers for the margin key or using of any unit suffixes will not work.

monochrome

Toggle monochrome or color output.

paper

Size the output for a particular paper size.

Legal paper sizes are described in the PWG 5101.1-2002 Standard (iso_a4, iso_a3, na_letter, na_legal, etc). The default paper size depends on the current locale. For instance, it is A4 when ru_RU.UTF-8 is used whereas it is letter for the en_US.UTF-8 locale.

size

Size the output with specific dimensions. If the size is “auto”, select the size that best fits the drawing.

The paper size set by the size key overrides that one set by the paper key. Note: setting only one number for the size key or using of any unit suffixes will not work.

gnetlist group

Table 2. gnetlist group parameters

Key Format Default
default-bus-name string unnamed_bus
default-net-name string unnamed_net
net-naming-priority predefined string: “net-attribute” or “netname-attribute” net-attribute
traverse-hierarchy boolean true

default-bus-name

Define the default bus name for the buses unnamed in the schematic.

Buses are still not used by any gnetlist backend, so this parameter is not useful yet.

default-net-name

Define the default net name for the nets unnamed in the schematic.

It is used to create netnames of the form “unnamed_netN” where N is a number.

net-naming-priority

Specify which attribute, net or netname, has priority if a net is found with two names. Any netname conflict will be resolved using the chosen attribute.

This option is used when both net and netname attributes are defined for some nets in your schematic and you want to specify which one should define the net names that gnetlist will use for netlisting. See the net= attribute mini-HOWTO and Master attributes list for more information on these attributes.

traverse-hierarchy

Decides if the hierarchy is traversed or not. If this is disabled then gnetlist will not go down searching for any underlying sources.

gschem group

Table 3. gschem group parameters

Key Format Default
default-filename string untitled

default-filename

Define the default file name for any new schematic files created in gschem.

It is used to create filenames of the form “untitled_N.sch” where N is a number.

gschem.library group

Table 4. gschem.library group parameters

Key Format Default
component-attributes comma separated list of attribute names *
sort boolean false

component-attributes

Holds a list of attribute names that are displayed in the component select dialog.

Symbol attributes in the dialog are sorted in the same order as they appear in the list. If the first list element is an asterisk “*”, all attributes will be displayed in the alphabetical order. An empty list will disable the attribute view in the dialog.

sort

Sort the component library.

If the value of this attribute is true, the component libraries are sorted alphabetically. Otherwise they are sorted in the order opposite to what they were added in.

gschem.printing group

Table 5. gschem.printing group parameters

Key Format Default
layout predefined string: “portrait”, “landscape”, or “auto” auto
monochrome boolean false
paper predefined paper size string locale dependent

layout

When using a paper size, set the orientation of the output. If “auto” layout is used, the orientation that best fits the drawing will be used.

gschem page orientation is intended to output pages to a printer rather than to PDF, so the value “auto” means that if you output pages to PDF you will get rotated landscape instead of ordinary. To get readable PDF with pages in landscape use instead the gaf export command, and set to “auto” the layout key in the export group.

Note: as of now, printing using the script print.scm doesn't use the layout key setting.

paper

Size the output for a particular paper size.

The default paper value depends on the current locale. See the notes on the paper size above in the description of the paper key for the export group.

monochrome

Toggle monochrome or color output.

It is intended that unlike the monochrome value in the export group, the key value in this group is false.

gschem.dialog-geometry.* groups

These groups include:

  • gschem.dialog-geometry.arc-angle
  • gschem.dialog-geometry.autonumber
  • gschem.dialog-geometry.color-edit
  • gschem.dialog-geometry.compselect
  • gschem.dialog-geometry.coord
  • gschem.dialog-geometry.fill-type
  • gschem.dialog-geometry.find-text
  • gschem.dialog-geometry.hide-text
  • gschem.dialog-geometry.hotkeys
  • gschem.dialog-geometry.line-type
  • gschem.dialog-geometry.log
  • gschem.dialog-geometry.multiattrib
  • gschem.dialog-geometry.pin-type-edit
  • gschem.dialog-geometry.show-text
  • gschem.dialog-geometry.singleattrib
  • gschem.dialog-geometry.slot-edit
  • gschem.dialog-geometry.snap-size
  • gschem.dialog-geometry.text-edit
  • gschem.dialog-geometry.text-entry
  • gschem.dialog-geometry.text-size
  • gschem.dialog-geometry.translate

There are two special groups having additional settings:

  • gschem.dialog-geometry.compselect
  • gschem.dialog-geometry.multiattrib

Table 5. gschem.dialog-geometry.* groups parameters

All dialogs
Key Format Default
x integer -
y integer -
width integer -
height integer -
gschem.dialog-geometry.compselect
Key Format Default
hpaned integer -
vpaned integer -
source-tab 0 or 1 1
gschem.dialog-geometry.multiattrib
Key Format Default
show_inherited boolean true

Note: all these values are automatically stored in the user configuration files. You can change them manually, but the values will be overwritten next time the dialog in question changes its size or other value mentioned in the table. If you edit the values when gschem is running they will be silently overwritten after it closes.

x

X position of the dialog window.

y

Y position of the dialog window.

width

Width of the dialog window.

height

Height of the dialog window.

hpaned

Width of the horizontal pane where components are selected in the component select dialog.

vpaned

Height of the vertical pane containing component preview in the component select dialog.

source-tab

This value determines which tab will be opened when you bring up the component selection dialog. 0 means that the “In use” tab will be chosen, 1 means that the “Libraries” tab will be chosen.

show_inherited

Visibility setting for inherited attributes in the multiattrib dialog.

gaf shell

gaf shell provides a Scheme Read-Eval-Print Loop (REPL) for automating processing of schematic and symbol files. It is designed to be used with the gEDA Scheme API. See the gaf(1) manual page for more information on the utility options, and info geda-scheme on which gEDA Scheme procedures you can use.

Fonts

On Linux, font configuring is handled by Fontconfig, and modern systems (particularly pango and cairo) rely on its library in looking up any font specified. You can provide the gaf command with a pattern containing the font name wanted and, optionally, with some settings for that font. Fontconfig performs matching of the pattern against all the fonts available in your system. The closest matching font is selected. This ensures that a font will always be returned, but doesn't ensure that it is anything like the requested pattern.

If you want to find out which fonts are available in your system, you can use the fc-list(1) utility from the fontconfig package. To check whether fontconfig could find an appropriate font by the specified pattern (or to see which font will correspond to your pattern), use the fc-match(1) utility.

See the fontconfig documentation for more information on how to specify the font name you want to use.

In some circumstances, the font system can even embed more than one font into your document. This occurs, for instance, if the most appropriate font chosen by fontconfig doesn't contain some glyphs for one of the languages used in the document. In this case it will add some other font that does have the glyphs required.

The next table lists possible settings (acquired from the Pango documentation) which you can use in your font name patterns. See also the Examples section below.

Table 6. Possible font settings

Setting Value
Style Normal
Oblique
Italic
Weight Thin
Ultralight
Light
Book
Normal
Medium
Semibold
Bold
Ultrabold
Heavy
Ultraheavy
Variant Normal
SmallCaps
Stretch UltraCondensed
ExtraCondensed
Condensed
SemiCondensed
Normal
SemiExpanded
Expanded
ExtraExpanded
UltraExpanded

Examples

Set up exporting

Use the “landscape” layout by default for a local project:

gaf config --project export layout landscape

Use the “letter” paper size by default for all your printouts:

gaf config --user export paper na_letter

Set paper size to the definite value of 1×2 inch for a local project:

gaf config --project export size "72;144"

Set margins as a half of inch for left and right sides and as a quarter of inch for top and bottom for a local project:

gaf config --project export margins "18;36;18;36"

This command will align your project's schematics to the right.

gaf config --project export align "1.0;0.5"

This command is wrong, it doesn't work for you even if your locale uses comma as a separator for floating point numbers:

gaf config --project export align "1,0;0,0"

This command, though, works in this case (e.g., in the ru_RU.UTF-8 locale):

gaf export -a 0,0:1.0 -o file.pdf file.sch

Note, that I use gaf export here, not gaf config.

To print all your schematics in color (note: “False” or “FALSE” will not work):

gaf config --project export monochrome false

Set up a custom user font:

gaf config --user export font "OpenGost Type B TT Italic"

Choose another font for a local project:

gaf config --project export font "Arial Bold"

Set up netlisting

Use more short net and bus names in all netlists created by the user:

gaf config --user gnetlist default-net-name net
gaf config --user gnetlist default-bus-name bus

Ensure that a local project will use hierarchical net names despite of settings in geda-user.conf:

gaf config --project gnetlist traverse-hierarchy true

Rename nets connecting to gnd-1.sym (and other symbols having the net attribute) if they have the netname attribute:

gaf config --project gnetlist net-naming-priority netname-attribute

Set up gschem

Use shorter names for new files:

gaf config --user gschem default-filename empty

Set up gschem library view

This command explicitly tells that you want to always show all attributes:

gaf config --project gschem.library component-attributes "*"

Please be careful when using this command in the command line. If you forget the quotes, your shell will substitute the first file name in the working directory file list for the attribute name. This is most likely not what you want.

Display only attributes that are in the filter list:

gaf config --project gschem.library component-attributes "refdes;device;description"

Don't show any attributes in the component select dialog:

gaf config --project gschem.library component-attributes ""

The same as before. However, this command will not work because the specified string separates values with commas instead semicolons, so the whole string will be considered one attribute name:

gaf config --project gschem.library component-attributes "refdes,device,description"

Sort the component library in gschem alphabetically:

gaf config --user gschem.library sort true

Set up gschem printing

Choose landscape as the default orientation for a local project when printing from within gschem:

gaf config --project gschem.printing layout landscape

Use the A5 paper size when printing from within gschem:

gaf config --project gschem.printing paper iso_a5

Always use B&W printing output from within gschem:

gaf config --user gschem.printing monochrome true

Set up gschem dialogs

Don't show any inherited attributes in the multiattrib dialog:

gaf config --user gschem.dialog-geometry.multiattrib show_inherited false

Note that you cannot use the --project (-p) key in the command above. This command works only in the user context and has no sense for local projects.

Using gaf shell

Find out the path to the gEDA user configuration directory, type:

gaf shell -c "(display (user-config-dir))"

The same for the system configuration directories:

gaf shell -c "(display (sys-config-dirs))"
geda/gaf_utility.txt · Last modified: 2014/07/28 08:00 by vzh