Class: AMS::ExtensionManager

Inherits:
Object
  • Object
show all
Defined in:
ext-ruby/ams_lib/extension_manager.rb

Overview

An extension manager for copying, loading, and removing dynamic linked libraries, C extensions, and rubies. Thanks to ThomThom for allowing me to extend his original C extension manager.

Since:

  • 3.5.0

Instance Method Summary collapse

Constructor Details

#initialize(ext_path, ext_version, experimental = false) ⇒ ExtensionManager

Note:

When the libraries are copied, they are obtained from EXT_PATH/libraries/stage/.

Note:

When the libraries are loaded, they are required from EXT_PATH/libraries/VERSION/ or TEMP_EXT_PATH/libraries/VERSION/ or EXT_PATH/libraries/stage/ (as the last resort).

Note:

Rubies are loaded from EXT_PATH.

Apply a staging technique to the dynamically linked libraries, to bypass overwrite issues when updating the loaded extension.

  1. The files within EXT_PATH/libraries/stage/ folder are used as resources for copying and are usually not loaded. These files are the ones that get overwritten when the extension is updated.
  2. Unless already created, the manager creates an additional version-specific folder within EXT_PATH/libraries/ and copies the platform-specific, staged resources into the folder. The libraries within the version-specific folder are the ones that get loaded.
  3. In case the extension is installed outside the user directory, where the file permissions are limited, the necessary staged resources are copied into a TEMP folder and are loaded from there.
  4. If all fails, as the last resort, loading is performed from the staged directory.
  5. An optional clean-up method removes outdated version-specific folders, and unregistered rubies, for the purpose of keeping the plugin directory clean.

Examples:

dir = File.dirname(__FILE__)
base = File.basename(__FILE__)
ext_manager = AMS::ExtensionManager.new(dir, "1.2.3")
ext_manager.add_c_extension('my_lib')
ext_manager.add_ruby('some_ruby_file_name')
ext_manager.add_ruby('some_other_ruby_file_name')
ext_manager.add_ruby_no_require(base)
ext_manager.require_all
ext_manager.clean_up(true)

Parameters:

  • ext_path (String) —

    A path to the extension.

  • ext_version (String) —

    A version of the extension.

  • experimental (Boolean) (defaults to: false) —

    The experimental option updates the libraries every time they are loaded. This is useful if the library is in development.

Since:

  • 3.5.0

Instance Method Details

#add_c_extension(filename) ⇒ void

Note:

All C extension files are be copied from EXT_PATH/libraries/stage/PLATFORM + BIT/RUBY_VERSION/.

This method returns an undefined value.

Add an .so/.bundle file that must be copied/loaded.

Parameters:

  • filename (String) —

    Library filename.

Since:

  • 3.5.0

#add_optional_library(filename) ⇒ void

Note:

All dll/dylib files are copied from EXT_PATH/libraries/stage/PLATFORM + BIT/.

This method returns an undefined value.

Add a library file that will be copied/loaded in case it's there.

Parameters:

  • filename (String) —

    Library filename.

Since:

  • 3.5.0

#add_required_library(filename) ⇒ void

Note:

All dll/dylib files are copied from EXT_PATH/libraries/stage/PLATFORM + BIT/.

This method returns an undefined value.

Add a .dll/.dylib file that must be copied/loaded.

Parameters:

  • filename (String) —

    Library filename.

Since:

  • 3.5.0

#add_ruby(filename, only_register = false) ⇒ Object

Note:

All added rubies are loaded last in the order they are added.

Add a Ruby file that will be required and ignored from cleanup.

Parameters:

  • filename (String) —

    Ruby filename.

Since:

  • 3.5.0

#add_ruby_no_require(filename) ⇒ Object

Add a Ruby file that will be ignored from cleanup but not required (loaded).

Parameters:

  • filename (String) —

    Ruby filename.

Since:

  • 3.5.0

#clean_up(clean_rubies = false) ⇒ void

Note:

This does not erase any files from the TEMP folder, as they may be used by other SketchUp versions.

Note:

This does not raise any errors upon failure to delete a file or a directory.

This method returns an undefined value.

Erase all unused libraries, c extension files, and unregistered ruby files (if clean_rubies is enabled).

Parameters:

  • clean_rubies (Boolean) (defaults to: false) —

    Whether to delete all unregistered Ruby files within EXT_PATH.

Since:

  • 3.5.0

#require_all ⇒ void

Note:

All .dll files are loaded first, in the order they are added, all .so or .bundle files afterwards, and all ruby files last. All .dylib files are expected to be loaded by a C extension.

This method returns an undefined value.

Copy and load all the required and optional files.

Raises:

  • (IOError, LoadError) —

    if a required file doesn't exist.

Since:

  • 3.5.0