Introduction

Actually, you don’t have to write Lisp to use .acme files. For example, you can simply add a tag and value for adding a search path, or a tag for only loading a menu in a .acme configuration file.

At program start, all instructions in .acme files are parsed and turned into appropriate actions, executed while starting the program (for example loading a menu) or while starting a document (for example loading Lisp for that document).

You can add, edit and delete .acme files. ACME looks for extension .acme and temporary turning files off can be achieved by renaming example.acme to example.acme.stop.

A .acme file contains tags and values, for example:

VendorName “ACME Corp.”

Yellow background: Mandatory tags and values. Tags can only occur once.

Green background: Optional and extensible tags and values. For example, two tags SearchPath is valid but using SearchPath1 and SearchPath2 is also valid, offering a way to influence the order. All green background tags are optional, occurrence 0 to many times is permitted.

Please pay attention to the syntax of the file, use a space between tag and “value” and omit tags without values.

The examples below form the following file. It contains all tags so it may be tempting to copy and paste in a text file:

ShortName "SolTwist"
Name "ACME SolidTwister"
Description "Do-It Yourself Solids Twisters, They Fly From Your Screen."
AppVersion "2.0"
VendorName "ACME Corp, Twister Division."
VendorUrl "https://nedcad.nl/"
VendorEmail "twisters@nedcad.nl"
HelpFileLocal "%appdata%\ACME\SolidTwister.pdf"
HelpFileURL "https://nedcad.nl/en/cadchup-acme/"
CADReleaseMin "20.1"
CADReleaseMax "21.0"
CADPlatform "3"
LoadCUI "%appdata%\ACME-inc\Twisters\TwisterButtons"
CommandString "._layer;_m;0;;"
SearchPath "%programfiles%\ACME-inc\Twisters\lisp"
TrustedPath "%programfiles%\ACME-inc\Twisters\lisp"
LoadPerDoc "%programfiles%\ACME-inc\Twisters\lisp\TwisterShapes.lsp"
LoadPerSession "%programfiles%\ACME-inc\Twisters\lisp\TwisterSettings.lsp"

Mandatory tags and values

ShortName

The application’s one word name.

Example:

ShortName “SolTwist“

The application’s short name, published during loading.

Name

The application’s name.

Example:

Name “ACME SolidTwister“

The application’s name, published during loading.

Description

A one line description of the application.

Example:

Description “Do-It Yourself Solids Twisters, They Fly From Your Screen.”

Description, one line, published during loading.

AppVersion

Application version.

Example:

AppVersion “2.0“

Published during loading.

VendorName

Name of vendor (you).

Example:

VendorName “ACME Corp, Twister Division.”

Published during loading.

VendorUrl

Site of developer.

Example:

VendorUrl “https://nedcad.nl/“

Published during loading.

VendorEmail

E-mail of vendor.

Example:

VendorEmail “twisters@nedcad.nl“

Published during loading.

HelpFileLocal

Location of local help file..

Example:

HelpFileLocal “%appdata%\ACME\SolidTwister.pdf“

Published during loading. Also added to ACME help function ACME-HELP.

HelpFileURL

URL of help on the net.

Example:

HelpFileURL “https://nedcad.nl/en/cadchup-acme/“

Published during loading. Also added to ACME help function ACME-HELP.

CADReleaseMin

Minimum valid CAD release.

Example:

CADReleaseMin “20.1“

Application will not run when CAD release is older than this version.

You can enter acadver in your CAD program to find the release.

CADReleaseMax

Maximum valid CAD release.

Example:

CADReleaseMax “21.0“

Application will not run when CAD release is newer than this version.

CADPlatform

On which CAD platform should your application run.

Example:

CADPlatform “3“

This is a bit code defined as follows:

“0” = Do not run application
“1” = Run on BricsCAD
“2” = Run on AutoCAD

The sum of bit codes determines in which programs your app will be launched. For example, if “1“, it runs only in BricsCAD, if it is “3“ (1+2) then it runs on both platforms.

Tip! This mechanism gives you a possibility to create different .acme files for different CAD programs, the BricsCAD file has value “1” and the AutoCAD file has value “2”.

Optional and extensible tags and values

LoadCUI

Load a menu on CAD program start.

Example:

LoadCUI “%appdata%\ACME-inc\Twisters\TwisterButtons”

Do not add an extension: “.cuix” is assumed in AutoCAD, “.cui” is assumed in BricsCAD.

CommandString

After loading the document: run these commands.

Example:

CommandString “._layer;_m;0;;”

When running LISP sequences at program start or on document load, no CAD commands should be run. Instead they should be added to function S::STARTUP for execution at the end. Tag CommandString can contain these commands with semicolons for “enter” keys. Since CommandString is extensible, it is better to use multiple tags than putting multiple commands in one string.

The example issues a layer command, Makes and sets current layer 0 end ends with an empty extra return. Other examples: “ribbonclose;“ and “menubar;1;“.

Due to AutoCAD, rejecting commands at program and document start, this tag is ignored for AutoCAD untill Autodesk solves this issue.

SearchPath

Add an entry in Support File Search Path.

Example:

SearchPath “%programfiles%\ACME-inc\Twisters\lisp”

Adding multiple paths does not slow down your CAD program. However, adding impressive libraries with parts in SFSP does slow down.

TrustedPath

Add an entry to trusted path.

Example:

TrustedPath “%programfiles%\ACME-inc\Twisters\lisp”

Not needed for BricsCAD.

LoadPerDoc

Load this file at document load.

Example:

LoadPerDoc “%programfiles%\ACME-inc\Twisters\TwisterShapes.lsp”

This file is run at the start of every document, for setting variables, Lisp commands, and so on.

LoadPerSession

Load this file at CAD program start.

Example:

LoadPerSession “%programfiles%\ACME-inc\Twisters\TwisterSettings.lsp”

This file is run only during start of the CAD program. For example, you can use it to create settings, like blackboard variables, that can be read in every document.

Using the priority-prefix exception

In acme.cfg, there is a section with priority-prefix locations. Main purpose is to be able to quickly apply patches. These locations are higher in the SFSP stack and will overrule existing code as long as file locations are not hard coded – in ACME not many things are.

So it is easy to put things like Lisp and translation files in such a directory.

Going one step further, to extend functionality, .acme files that are placed there – and only there – are also parsed. They are treated like standard .acme files, so you can load menu’s, autoload Lisp, and so on.

Additional information

You are in charge

Our approach is KISS. If you want to put Lisp code in %appdata% it’s fine. Perhaps %programfiles% is smarter, but it is not up to Autodesk, Bricsys or us.

To keep things flexible, this version is stripped from “intelligent” decisions. For example, if you use LoadPerDoc or LoadPerSession, then you have to take care of SearchPath too (and TrustedPath when using AutoCAD). This is a bit extra work but doesn’t collide with other solutions, like a standard deployment with corresponding settings.

About LoadPerDoc and LoadPerSession

These tags needs some explanation first. LoadPerSession is only run once per CAD session, while LoadPerDoc is run when opening a document (new or existing). LoadPerSession is run first. LoadPerSession can pave a way by taking care of typical “once per session” settings, like registry settings, loading that menu and defining global variables that can be used by LoadPerDoc. This way, document loading can be speeded up, it is good programming practise and not new. BricsCAD and AutoCAD have files for these too:

When\Vendor	BricsCAD	AutoCAD	ACME
At program start	on_start.lsp	acad.lsp	LoadPerSession
At document loading	on_doc_load.lsp	acaddoc.lsp	LoadPerDoc

In AutoCAD, the standard behaviour of loading order is unpredictable. The order of the XML file is not by definition the load order. What is wanted is an order where first CAD system settings are handled and next the document settings. That is what ACME takes care for behind the scenes. LoadPerSession only runs once per CAD session and always (!) before LoadPerDoc. That makes ACME attractive to use, in order to get rid of the annoying AutoCAD behaviour (BricsCAD does load in the right order by the way). For example, you can use (setvar registry-setting-x) in LoadPerSession, in order not to repeat it in LoadPerDoc for every document.

Another thing to consider: Don’t forget to check SearchPath and TrustedPath.

Troubleshooting

ACME collects information and takes action in a grouped way – doing all menu actions for all applications in one step, doing all search path modifications in one step, and so on. It is important to realize this. As a consequence, program loading and starting documents is pretty fast. The downside is that one bug in one application can terminate the complete sequence of instructions.

However, there is a positive side too: By reading which application causes error messages – the last action when pressing F2 – you can easily determine which application is causing trouble.

Now that you know this, you should disable this faulty application. The safest way is to simply rename its .acme file into another extension: ApplicationX.acme becomes for example ApplicationX.acme.paused. These files are located in %AppData%\NedCAD\ACME\Apps. Start your CAD program again to make sure no errors occur and contact the vendor for support. Needless to say an error in ACME itself is a possibility too, in which case you should contact us.