Naming Issues

Any SketchUp plugin will define names in at least a few namespaces. In order to "play nicely" with other plugins (and SketchUp itself), it should keep this presence as unobtrusive as possible, consistent with its functional requirements. This page examines some naming issues that affect the Extension Framework (EF) and the plugins it manages.

Directories and Files

SketchUp normally runs on either Mac OS X or Microsoft Windows. Both of these operating systems use hierarchical file systems. SketchUp defines (and enforces, in come cases) OS-dependent conventions regarding the location and naming of directories and files.

  • The extension's "loader" script must reside in a location
    (eg, .../Plugins) that is appropriate for the OS.

  • The script must have a unique name with an "rb" extension.

  • Loader scripts are executed in (OS-dependent) "name" order.
    So, bar_loader.rb would load before foo_loader.rb.

    Note: The execution order determines the position of entries
    in the Plugins menu, SketchUp Preferences dialog, etc.

  • Plugins (eg, loader scripts) should be the only Ruby (*.rb)
    files that are located in the plugins directory.

  • Normally, any associated files for a plugin should reside
    near the plugin, in a similarly-named sub-directory (eg, foo).

EF follows these practices, with minor additions and exceptions:

Additions

EF generates the directory and file names (in the Plugins directory) that are used by the extension sets it manages. For example, consider the CFCL/Public Extension Set (ES):

  • The loader script is named com_cfcl_public.rb
    (com_cfcl_public_dev.rb for development mode).

  • The associated sub-directory is named com_cfcl_public.

Rationale

EF's names in the Plugins directory (and its single global) use the popular Reverse-DNS naming convention. For example, because CFCL owns the domain name cfcl.com, it has the moral authority to derive other names from it.

This approach precludes most name collisions, indicates the origins of entities, and "clusters" related content in (at least) the Plugins directory.

Private Trees

EF also defines a few "private" file trees (eg, in .../Library/SketchUp):

  • SketchApps_dev - development extensions, etc.

  • SketchApps_tmp - temporary (session) files.

  • SketchApps_use - usage (eg, config, log) files.

Loader Attributes

Each loader script creates a SketchupExtension, using the ExtensionsManager API, eg:

foo_loader = SketchupExtension.new(foo_name, foo_path)

  • The extension's name will be used in a SketchUp dialog,
    so it should be memorable, short, and unique.

  • The extension's path will be used to load the extension,
    so it should (with very few exceptions) be unique.

Ruby Constants

Any Ruby constants (eg, FooClass) that are defined outside of a module (or class) are global by default. So, Best Practice is to wrap each extension in a Ruby module. This provides a private namespace for its internal (eg, class, method, variable) names.

Unfortunately, if the module itself has a name (eg, FooModule), a conflict could still occur. So, EF uses an anonymous module for this purpose, eg:

foo_module = Module.new do ...

EF uses no global constants of its own (though libraries such as ERb are still an issue). To avoid conflict among its own managed plugins, EF also wraps each one in an anonymous module.

Ruby Globals

Any global that an extension (or other plugin) defines will be visible throughout Ruby's run-time environment. So, Best Practice is to:

  • define as few globals as possible

  • use long, distinctive names

Only a single global variable ($com_cfcl_efd) is used for EF data.


This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r4 - 24 Apr 2013, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email