[PREVIOUS] [NEXT] [UP]

Folders

Folders are used to group NST units into smaller sets that are functionally related. This section will explain how to create new folders and how to make them accessible from Neo.

How to load existing folders into Neo

When Neo starts, it will seek a file .neofolders (first in your current, then in your home directory) to find out which folders to load during startup. A typical line in .neofolders has the form

foo    $(HOME)/thisdir/myfolder

and specifies one of the folders to load during runtime. The first token is the folder's "short name" (its first 10 characters will be shown on a Neo button to select that folder). The second token is the path to find the folder.

The folder itself is either a directory or a shared library (in the latter case, it should be given with the suffix that characterizes shared libraries within the particular operating system). In addition, a '#' character makes the rest of a line into a comment.

A second way to load one or several folders is to append their names, separated with '+' marks, to the name of the circuit that is to be loaded into neo, e.g.,

neo -i mycircuit+myfolder1+path/myfolder2

Note that in this case neo will first load the folders, and then the circuit (so that it can use the folders).

How to group folders into folder groups

When there are many folders, the Neo command menu window may grow too long. Folder groups allow to "contract" groups of folders into single buttons. A folder groups is defined through a single token (non-comment) line in .neofolders. The group name is specified by the token, and the group members are all folders that are specified between the single token line and the next (or the end of file, whatever comes first). When the token is enclosed in brackets (such as [groupname]), the foldergroup will initially be "closed" (all folders of the group will be loaded, but only a single button, labelled with the bracketed folder group name, will appear in the command menue for the group). Toggling that button will "open" the group (cf. below). Otherwise, the foldergrup will be "open" and appear in the command menu as a button labelled with the group name, followed by a button for each folder of the group. Toggling the folder group button will close the group. Toggling any of the group member buttons will display the contents of the folder in Neo's folder window.

Folder types: static, dynamic and circuit folders

A static folder is a group of units that are permanently compiled into Neo. Such folders need not be loaded, they are present automatically (the source file ... specifies which folders are compiled into Neo).

A dynamic folder is a shared library that comprises a group of compiled NST units. Such libraries can by loaded into Neo dynamically, either during start-up or later (they also can be unloaded again).

A circuit folder is the most flexible of all. It is a directory that contains (in separate subdirectories) zero or more shared libraries with compiled NST units, and zero or more loadable NST units (these are units that are implemented in the form of encapsulated NST circuits constructed from within Neo). Further subdirectories may accommodate documentation. Like a dynamic folder, a circuit folder can be loaded dynamically at startup or later.

How to create a circuit folder

To create a circuit folder, create a directory with the following subdirectories:

circuits : this will accomodate the loadable NST units of the folder.
o.$ARCH : this will accommodate any shared libraries that implement compiled NST units of the folder ($ARCH = "linux", "solaris" or "sgi")
man : (optional) may contain subdirectories cat3 and html3 for manual pages in nroff or html format
examples : (optional) may contain example circuits illustrating the usage of units from the folder

In addition, there should be a file named synopsis that contains a listing of units that shall appear as icons when the folder is displayed in Neo's folder window. Only those units that are listed in the synopsis file will be extracted from the shared library(s) in o.$(ARCH). New: a hat  "^" in front of a name listed in the synopsis file will switch the default instantiation mode of the loadable icon of that name  from "by copy" to "by reference" (cf. below).

A synopsis file can contain the additional keywords PACKAGE followed by a package name and EXPORTS, followed by the list of the to-be-ordered icon units. A hat symbol "^" (separated by white space) after the package name will switch all loadable units into by-reference default instantiation mode. A "^" (again separated by white space) after EXPORTS will only switch the listed units. Here is an example of a synopsis file.

How to use a circuit folder

To use a circuit folder, either specify it in .neosrc to load it at startup, or load it during runtime, using the syntax shortname=path instead of the filename specification in the "Load" command. Here, "shortname" is the folder's short name, and path its full path. Alternatively, you can try a "+shortname".

You can fetch instances from a circuit folder in the usual way by dragging them from the folder into the circuit window. In addition, you can add new units to a circuit folder (or update existing ones) by dragging a unit from the circuit window into the folder window.

Usually, loadable units in circuit folders should be saved without their data part (the presence of the data part usually will cause problems when the unit is instantiated with different parameters than saved). An exception are parameterless loadable units. For them, it is safe to include their data part, since a newly created instance will always be an exact copy. Parameterless loadable units may thus, e.g., be useful as pure "data containers".

About reference instances

When a unit from a circuit folder is created in the normal way, Neo will instantiate a (possibly re-parametrized) copy of the chosen ``source'' unit and insert it in the destination circuit. After that, the origin of the created instance is ``forgotten'', i.e., it is indistinguishable from an instance that has been assembled manually. Consequently, when it is saved to a file and later reloaded, there will be no involvement of the circuit folder from which it had been created originally.

As a result, any subsequent changes to a unit in a circuit folder will not affect any of the circuits containing instances that were derived from it.

However, for many uses it would be desireable to keep a permanent link between a unit in a circuit folder and the (possibly re-parametrized) instances that were derived from it. This would allow, e.g., to ``transmit'' any improvements or corrections of a unit to all its ``descendants''. At the same time, however, this will entail the responsibility to make only changes that do not break the compatibility of the derived units in their embedding circuits.

When a unit is created from a circuit folder, Neo allows to keep such a permanent link to the ``source'' unit by creating the new unit as a so-called reference instance of the source unit in the folder. This will not change the execution behavior of the new unit, but a reference instance can only be inspected, not changed. This ensures that it always "stays in sync" with its source unit in the circuit folder.

To create reference instance, you must first toggle (with the left mouse button) the letter 'o' so that an additional hat-symbols "^" appears, which indicates that now any further instances will be created as reference instances.

Versioning of loadable units

Using the referenceing mechanism must rely on a sufficiently flexible scheme to for providing new versions of ``source'' units and/or circuit folders without running the risk of breaking many circuits. This is achieved by allowing a folder to contain for each unit several versions (distinguished by a pair of version numbers) so that old versions can be kept for backward compatibility. Additionaly, entire folders can also coexist in several versions, for similar reasons.

When you create an instance interactively from a circuit folder, Neo automatically picks always the newest version (a version is specified by a pair .M.n, such as .4.1, that is appended to the base name of the circuit file of the unit. The left number is the major version number and distinguishes between potentially incompatible versions; the right number is the minor version number and distinguishes between compatible versions of a unit). To selectively load an older version, hold the Shift key down while fetching the icon. You will then be prompted to specify a different version.

Reference instances are always stored with their version number, and when Neo later re-instantiates them it will use the newest version in the folder that has the same major, but highest minor version number. In this way, a circuit that has been built with reference instances can automatically pick up all compatible improvements to its units while avoiding the incompatible ones (which differ in the major version number). This, of course, requires that version numbers for newly created units are specified such that changes in the minor version number always guarantee compatibility, and that at least one version for each major version number is kept in the folder.

For more details about Neo's versioning scheme (which also allows different versions of an entire folder), see the manual  Versioning.

[PREVIOUS] [NEXT] [UP]