Tag: programming

Building a commercial grade lisp plugin installer in 5 easy steps

Rumors about the death of AutoLISP have been floating around for many years, but fear not, those rumors are greatly exaggerated. Bricscad and ZWCAD both have excellent support for lisp plugins, so well-written lisp code is truly cross-platform and enjoys a large and growing audience. Unlike other languages, the vast majority of lisp code works unmodified on any hardware architecture, in any version of Windows, and inside any host application that supports it, including AutoCAD versions released more than a decade ago. On top of that, OpenDCL gives lisp developers the power of a modern event-driven user interface that can put their lisp plugins on the same playing field as plugins written in any other language. This is a powerful combination, and given lisp’s low entry cost, it is not surprising to see lisp continuing to enjoy strong support in the developer community.

There’s just one thing missing: an easy way to install a lisp plugin on an end user’s computer. It’s a common refrain. How do you build a setup program for a lisp plugin? There are any number of free and low-cost installers available, but they are all designed for installing an executable program, not a plugin that must be configured to run inside a completely independent host application.

At one time there was a package called AcadInstall that was designed for AutoCAD add-ons, but that tool is long defunct. Autodesk has invented application bundles with the supposed benefit of making it easier to install and manage plugins, but these are not well documented and only work with recent versions of AutoCAD. For ManuSoft plugins, I use Visual Studio’s Setup and Deployment projects along with an extensive amount of custom C++ code to perform all the configuration necessary at install time. This works great for my needs, but it is well beyond the ability of most lisp developers.

After several recent online discussions with lisp developers struggling to get a working setup program, I set out to find a solution to this vexing problem. It turns out that after some initial work it’s actually not that hard to pull off a very professional looking setup program for a basic lisp plugin. In fact, if you follow these steps, in less than 10 minutes (5 minutes if you have a fast internet connection) you will have a working setup that installs a lisp plugin on any version of AutoCAD, Bricscad, or ZWCAD+. The best part: everything you need is free (as in beer)!

So, let’s get to it.

  1. Download and install Unicode Inno Setup QuickStart Pack from the Inno Setup Downloads page.
  2. Download my LispPluginSetup freebie and extract the files into a new folder somewhere.
  3. Download my LspLoad freebie and extract the files into a new subfolder named LspLoad.
  4. Double click on MyLispPlugin.iss. It should open in Inno Script Studio. Choose Project -> Compile.

At this point you should have a new Output subfolder with MyLispPluginSetup.exe inside. Go ahead, run it. After you’ve installed the MyPlugin sample, start the host application of your choice (the setup program configures all of them). If all went well, MyLispPlugin should display a command line message at startup alerting you to the fact that MYCOMMAND1 and MYCOMMAND2 are now available for use. Go ahead, try them. When you’re finished playing, it should uninstall cleanly (except for the new addition to TRUSTEDPATHS in AutoCAD 2014) when you choose Start -> MyCompany -> MyLispPlugin -> Uninstall My Lisp Plugin.

That was almost too easy, right? Well, not so fast. You’ll need to make some changes to adapt the sample for your own plugin. Take a look at the installation script in Inno Script Studio. Click on the Inno Setup Script item in the project tree to see the entire script as a flat file. Right near the top of the script, it should be obvious that you’ll need to change the basic plugin information preprocessor constants to adapt the script for your own plugin. Obviously your plugin will have a different base filename, and quite probably more files. It may have more registry keys and other basic setup stuff. In addition, you may not want to support all possible versions and flavors of each host app (in that case you’ll need to comment out or remove the associated item in the Files section). You get the idea, I’m sure.

Step 5 is modifying the sample script to adapt it for your own plugin. So easy, even an engineer could do it!

Don’t catch what you can’t handle

One of the cardinal rules of C++ exception handling is “don’t catch what you can’t handle”. Of course there are always, er, exceptions to the rule, but the basic principle always holds. The consequences of violating the rule are less severe in the .NET world, but even there it’s a good rule of thumb.

Back in the old days you needed permission from a deity before you could use catch(…) to catch all exceptions. By the turn of the century, an Executive Order was sufficient. These days I see posts all the time on programming forums that go something like “My plugin crashes when I call ThirdParty::Function(). How can I catch all exceptions in ThirdParty.dll?” Bzzzt. Foolish programmer alert!

The .NET framework allows exceptions to be used for signaling, so inexperienced programmers often think that’s how they work in C++ as well. I think this is a case where the less rigorous .NET programming model bleed-over effect has negatively impacted C++ programming.

C++ function declaration tips

Creating and calling functions is one of the most fundamental tasks in C++ programming. The function declaration serves as the primary description of a function’s interface – or contract – with callers, thereby making it the most important piece of code documentation. A good function declaration should convey as much information as possible. I’m sure an entire book could be written on the topic of function interface design, but I’ll just touch briefly on a few factors to consider when designing a function’s interface.

Error handling

Simple one-purpose functions should leave all or most error handling to the caller. This is more efficient because it eliminates error checking overhead on “known good” input values. A common pattern is a low level function that performs no input validation along with a high level function that does (and then calls the low level function to do the work). Such a design pattern gives the caller maximum flexibility.

If the function must return error (or other status) values, it should do so via the return value whenever possible, and it should define an enum or type alias (typedef) so that the return value type name makes it clear that the value is a status. Note that using the return value as a status may necessitate extra arguments passed by reference so the function has a way to return a result to the caller without using the return value.

Signed vs. unsigned

Consider this function:
int CountWords(char* pszInputString);

The int type is a signed value, but a count is always zero or greater. The return value should at least be unsigned int, or better yet size_t:
size_t CountWords(char* pszInputString);

Likewise, arguments that must never be negative should always be declared as an unsigned type.

By value or by reference

If the caller needs to pass arguments that the function will modify, they must be passed by reference. If the argument will not be modified, then it should be passed by value if it is a trivial type, else by const reference (except in unusual cases). For example:
bool CountWords(const CountOptions& options, char* pszInputString, size_t& ctWords);

Const or not

Incoming arguments that will not be modified should be declared const. This conveys a clear guarantee that the function will not try to modify the incoming value. Proper const delarations also give the optimizing compiler more ways to optimize the code.

Since counting words does not require the input string to be modifed, the CountWords() function’s string argument should really be const char* const (constant pointer to constant char) instead of char*:
size_t CountWords(const char* const pszInputString);

Now the caller can pass a string literal or any other string (even an MFC CString), and be assured that the CountWords function won’t change it.

Source code annotation language

Source code annotation language (SAL) is a fairly recent Microsoft specific development. It consists of predefined macros that help more fully express the constraints and purposes of function arguments without changing the compiled output. SAL helps convey additional information about the function’s contract with the caller, and it also helps the compiler detect potential problems at compile time by performing additional static code analysis.

As you can see below, source code annotation can get a bit messy. I rarely use source code annotation in my own code for this reason and also because it’s not portable to older versions of Visual Studio without extra work. Source code annotation is most appropriate in an API that will be consumed by others, and even then it should be considered carefully in light of its readability and portability trade-offs.

Exception specification

In C++, the exception specification conveys information about what kinds of exceptions a function may throw, either directly or indirectly via functions it calls. If a function cannot throw an exception, you should include the empty throw() suffix on the function declaration.

Putting it all together

Suppose we create a higher level function that validates the input, then calls a lower level function to count words. We might end up with something like this:

size_t CountWords(_In_z_ const char* const pszInputString) throw();

enum Status { eOK, eNull, eError, };

_Check_return_ Status ValidateAndCountWords(_In_z_ const char* const pszInputString, _Out_ size_t& ctWords) throw();