Custom package development: Basic steps

Question

Every once in a while, I write a generic function that I use quite often for months to come. However, package development in Mathematica is not very well documented from what I can tell, and I was not able to find a coherent description online (most of them deal with tiny issues and bits). In the end, I usually give up and copy+paste the function in every new notebook, which isn't really the way to go.

Does anyone here develop packages himself and could walk me from "open Mathematica" to "save as something that can be included via <<Package`" or give me a good reference?

Answer 1

I think what confuses most users who are new to packages is the larger question of where to put them and how to use them. I am going to discuss this in a larger context.

Suppose you are working on some significant or extended topic, which we will call TopicX. This topic might include many notebooks of various kinds and several packages, and perhaps later WRI style paclet documentation.

First you need a place to collect all your work on TopicX. The best place to collect this is in a TopicX folder in your private Applications folder. You can find this Applications folder by evaluating $UserBaseDirectory in Mathematica and then looking for the pre-existing Applications folder. Many users find some reason to put their applications elsewhere, but I think this is the best and standard location for a number of reasons, which I won't expound on here.

Within the TopicX folder you could build a folder structure for your own notebooks and other files associated with the topic, according to your own preferences. So far, no package.

As you work on the topic you will find it convenient to develop various routines associated with the project. You might develop them in a notebook proper and then move them to a Routines section at the top of the notebook. You might leave a routine there for a while and even copy it from notebook to notebook until you are satisfied that it works properly. I often call this "package purgatory". For these routines write usage messages, a SyntaxInformation statement, Attributes if any, Options definitions if any, error messages if the routine checks for errors. If all this is done, the routine is ready for "package heaven".

An application may have more than one package associated with it. I am going to assume that this is the case, or a future possibility, and give the packages names other than TopicX. So let's assume that your first package will be named Package1. In the TopicX folder create a new file named Package1.m. You could do this by opening Mathematica, using Create New> Other> Package, and then saving the file as Package1.m in your TopicX folder.

Package files can have sectional organization just as regular notebooks. You may wish to create sectional organization for the BeginPackage and Usage messages, and for the Private section, and for an End section. You may also want subsections for individual routines. According to your taste. Package files can also contain Text cells for annotation or notes.

The actual Mathematica code in a Package file is contained in Code cells. These are automatically Initialization cells and they are evaluated when the package is loaded. Cells that have the Input Style are not part of the package. (Converting a Code cell to an Input cell is a way to save an old version of a routine.) You can copy your routines from the notebook where they were developed to the package file. Usage messages to the Usage section and code to the Private section. Depending on how you copy you may have to switch Input cells to Code cells using the context Style menu. Code cells, especially usage messages often do not conveniently break and require horizontal scrolling. Sometimes it helps to temporarily switch them to Input cells for editing.

Following the folder structure, the BeginPackage statement will be:

BeginPackage["TopicX`Package1`"]

and the package could be loaded from anywhere with:

<< TopicX`Package1`

However, there is another very convenient feature that WRI has implemented. If a user executes the load statement without the package name as follows:

<< TopicX`

then Mathematica looks for an init.m file within a TopicX/Kernel folder and evaluates it. So create a Kernel folder within TopicX and an init.m file within it, and include the statements:

Get["TopicX`Package1`"]
Get["TopicX`Package2`"]  

if there are other packages in the application.

That's it. I won't discuss the details of package code since that is pretty well discussed elsewhere.

Later, if you want to add WRI paclet documentation, you could obtain Wolfram Workbench. You could just transfer the package files to Workbench and start writing Guide and Function pages. One important thing to remember is that all the routines from all the packages in TopicX are included in a single documentation paclet for TopicX.

Answer 2

You'll want to at least look at chapters 1-2 of Roman Maeder's Programming in Mathematica for starters. That was the walkthrough I used when I was starting out with package writing. I'll update this answer if I can remember the other references I used.

In particular: pages 47 to 48 of the third edition provide the listing of a file, Skeleton.m that is a template that you can use; just replace and/or delete stuff as needed.

Answer 3

I like to use the Mathematica plugin for Eclipse (or the Workbench) for development. It's very simple to build packages, you can write the documentation for your functions (as well as Guides and Tutorials) and you can deploy your package to your Mathematica installation so both your functions and the documentation are integrated with the built-in ones.

It works very nicely (and the same for webMathematica if you're interested).