Package Authoring: An Introduction, Part 1
Of all the things I love about Max, one of my favorite features is certainly Packages. Using the Package Manager I can easily extend Max with the incredible work done by others with a single click. Packages don't have to be in the Package Manager, however, and there is a lot of amazing work available in Package format to be downloaded from across the web.
Packages aren't just for distributing work. I use packages every day for organizing work on my computer, regardless of whether it will be shared or not.
In this series, I will share some best practices and insights for authoring your own packages. When we're done, you will be equipped with some powerful tools and the confidence to distribute quality packages to others either directly or through Cycling '74's Package Manager.
Part 2: Build on the foundation in the first tutorial to address the details, subtleties, and dynamics of a polished package that is ready to be shared with the world.
Part 3: Author reference documentation for Max.
What is a Package?
A package is a folder. That's it.
Two criteria make the folder special: the folder be located where Max can find it, and the contents of that folder follow some simple naming conventions.
A package is any folder located in one of these locations:
- Inside the Max application bundle. This is how Cycling '74 includes the BEAP and VIZZIE packages bundled with Max. It is not a location for use by third-parties.
- In your Documents folder. This will contain all the Packages installed using the Package Manager, any Packages that you download and copy here yourself, or any Packages that you create for your own use.
- In a Shared folder. This is a location where you can install Packages that will be available to all users on a particular system.
You can also refer to the official documentation for the most up-to-date details, including the specific path information for your operating system.
Getting Started with Making a Package
For this tutorial we will gather some of the patchers, externals, and other materials produced during the recent series on the FFT so that we can bundle it together as a package.
The first step is to make a Package (remember, it is simply a folder) in the documents location:
To start, our package will contain some of the Max patchers we created. So we will add a folder called "patchers" and then drag the patchers we want into that folder:
Now we can launch Max and open the Package Manager:
When it opens, we can click the button in the upper-right of the window to show Installed packages.
In the lower left we can see our new package, fft-tutorials! The patchers are available to use. For example, if we start typing "fft-" in an object box the abstractions appear in the auto-completion list:
Adding More Content to the Package
Creating a package with some patchers is a great start. We can add other types of content as well including images, sounds, media, documentation, etc. The types we can add and the names of folders for those types is documented in the Packages Guide.
As an example, we can add the externals and the help patchers from Part 5 of the FFT series.
In the case of the externals we are able to add both the Mac (.mxo) and Windows (.mxe and .mxe64) versions of the externals so that our package will work on both platforms.
We can even include the source code in our package if we want to distribute it as open-source.
If we refer back to the official Packages Guide we will notice that some folders will be included in Max's search path, such as "externals", "help", and "patchers". This means that Max will be able to find any content in these folders. Other folders, such as this new "source" folder is not included in Max's search path. This means Max will ignore the content in this folder, while still allowing you to distribute the files as a part of the package.
Advanced Package Creation
As you can see, it is easy to get started making simple packages.
There are several topics we will be covering in the next two parts of this series that will help you to create the very best packages. These topics will include creating an icon or cover image, specifying system requirements, providing readme and license information, authoring reference pages and tagging files with metadata.
by Timothy Place on
Sep 11, 2017 7:22 PM