ExtensionPackageHOWTO

This page is outdated. It is kept for historical reasons, e.g. to document specific decisions in Inkscape development.

Packages as Extensions: a HOWTO

This page will teach you how to create and distribute one or more extensions that rely on a package.

Start by creating a root folder to contain your package and extensions i.e. play-svg

You must make a package out of any modules you have. Add all of the modules into one folder inside the root directory i.e. play-svg/playsvg and create a package from those modules. If you do not know how to create a python package, follow the instrctions here: [1].

Secondly, you must create the necessary .inx descriptor and .py Effect object that use your package. Make sure to use the full path name when importing into your Effect object file i.e. Place the .inx and .py files for the extensions in a folder inside the root folder

import playsvg.path
OR
from playsvg import path
OR
from playsvg.path import * 

Use python distutils to create a setup.py script that will install your package onto the users system so that the libraries will always be available to python regardless of your current working directory. The setup script should reside in the root folder, in this case play-svg/ The user documentation of python distutils here.

An example of a setup.py script here

#!/usr/bin/env python
from distutils.core import setup
import os
import glob
dataFiles = []
if os.name == "posix":
    print "Inkscape extensions will be automatically installed on this Linux-based system"
    dataFiles.append(("/usr/share/inkscape/extensions/", [i for i in glob.glob(os.path.join("inkex", "*.*"))] ))
else:
    print "You are not running Linux, therefore you must install Inkscape extensions manually by copying files in the inkex directory to the Inkscape extensions directory on your system"
setup(name='playsvg',
      version='0.2',
      description='playsvg: making graphical programming as easy as py',
      author='playful_geometr',
      author_email='justinbarca@gmail.com',
      url='http://sourceforge.net/projects/play-svg/',
      packages=['playsvg'],
      data_files=dataFiles
)

This setup script will install the python libraries onto your system. It will also install the Inkscape extensions, but only for Linux systems. Help is needed to figure out how to discover where the extensions reside in other operating systems, particularly Windows and MacOSX. Users of Windows and MacOSX will have to manually move .inx and .py extensions files to the required directory.

An example of a MANIFEST.in file here:

include *.txt
recursive-include inkex *.inx *.py
recursive-include scripts *.py

Editing this file is required to ensure that all of the files that are not a part of the package you create will be copied into your distribution. In this case, the scripts folder contains a set of example scripts that use the package modules, extraneous to the installation of the extension(s) but useful to developers that might use the libraries in their own python coding.

These examples for creating a sdist of your python code were taken from pLAySVG, a set of libraries for the generation and manipulation of SVG in a simple Object-Oriented fashion. You can take a look at the code for a full example of a distributed Inkscape extension based on a package.

To create a distribution, a compressed file containing all of the files for your extension, including the setup script, go to a terminal, change the working directory to be the root folder, and then type:

python setup.py sdist --formats zip,gztar

This will create both a .zip and .gz file containing all of the code needed to install your extensions.

From there, the user needs to extract the files in the archive, run the setup script in the root directory like such

python setup.py install

and, if they're not using Linux, move all of the files in the inkex directory to the necessary Inkscape extensions folder.

Voila, there you have it, distributing Inkscape extensions as packages is as easy as py...