Getting started with the Vectorworks SDK, Part 3

Update 2013-04-02: Sorry, everybody. I’m calling it. It’s been over two years, and I’m never going to finish this. Feel free to email me about your SDK adventures if you’re well and truly stuck and I’ll try to help you out.

We have basic plug-in theory covered.

What follows is what you will need to install to play along at home, so please get your tools ready while you breathlessly await Part 4. I shall assume you’re running an Intel Mac with Snow Leopard 10.6.6. (My own hardware is a 2006-era Mac Pro; if you have the juice to run Vectorworks 2011, you have the juice to build plug-ins).

Install Homebrew

This is a useful prerequisite, but not required. There are a few Unix command-line tools you will need. I’ve found Homebrew to be the simplest way to get these installed and keep them up-to-date, since they have to be built from source, many of them depend on other tools, which depend on other tools and libraries, &c.

Install ack

You will want ack. Given the transitional state of the official documentation, I seem to spend a lot of time combing C++ header files for argument order, return values, examples of function usage, &c. Homebrew provides a command line version with brew install ack, and I also have the AckMate plug-in installed in TextMate. (Note that TextMate is in no way necessary for SDK development, but it’s useful for Vectorscript development).

Install git and Gitx

I use git for version control. You will want version control.

(NB: It will start to greatly annoy you that Vectorworks uses pessimistic locking at a grain that makes no sense in architectural teamwork—ie. a file on disk—and offers no version control or design option tools of any kind. This is one of my longstanding hobbyhorses. Feel free to join the cause).

git has a brutal command-line user interface pasted on top of a shockingly elegant, simple conceptual underpinning. Expect pain, but know that it’s worth it in the end. Book some couch time with gitcasts. Installing git is optional, but highly recommended: just brew install git. At a bare minimum, use Subversion should you already know it.

I rely on the open-source Gitx as a GUI. I use the brotherbard fork, which has some nice features that may make their way back into the main line some day. Tower looks promising, but I don’t have any real experience with it.

Any git GUI is unlikely to include every feature of the command-line version, so at least get comfortable with basic operations from the command line, however irritating it may be.

Install rake

I use rake to make sure the dozen or so tedious little steps required to build and deploy happen the same way every time. Many tools could work here – including plain old make, or ant if you happen to have a S&M thing for XML – but I’m simply most comfortable with rake. Because Ruby comes stock on Mac OS X, you can install it with a simple sudo gem install rake. Or, you can get fancy with the Ruby Version Manager, as I do; I tend to have several versions of Ruby installed at any one time for my other development projects.

Install Xcode

You will most certainly want Xcode, available from Apple.

(Update: Xcode is now free through the Mac App Store. Ignore the next three paragraphs).

The easiest way to get this is through the Mac App Store, where it’ll run you USD$5. The harder way is to get them as part of a Mac or iOS developer membership (USD$99/year). Regrettably, it’s only as of last week that these developer tools are no longer free. Putting aside for the moment any judgment on the principle of charging at all, I would argue the dev tools are definitely worth more than five bucks.

(It’s worth noting that (a) the sufficiently hardcore, cheap, or doctrinaire among us could build a Vectorworks plug-in using only emacs or vim, gcc and Rezilla, all GPL open source; and (b) life’s pretty short. Go buy Xcode).

Beware: the current version—Xcode 4—is a top-to-bottom rewrite, and is less than a week old as of this writing. For the near future googling whatever particular problem you’re having is likely to turn up stale hints for Xcode 3.

Install the SDK

Finally, the meat: Nemetschek makes the Vectorworks SDK available for free download. Pick the first link. Accept the license agreement, nab the Mac version of SDK 2011 and unzip it. It consists of a giant pile of .h and .cpp files, some sparse documentation, a couple of non-beginner-level sample projects, and .a static libraries that Nemetschek has compiled specifically for Mac OS X. We’ll talk about where to locate the SDK in the source tree in the next part.

In Part 4, we’ll (finally) get down to some actual coding.

Mon 14 Mar 2011