Package Authoring: An Introduction, Part 1

Overview

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.

Package Manager Overview

Package Locations

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

series

Klangschmied
Sep 12 2017 | 8:10 am
Hi Tim, thanks for this tutorial (recently I asked in the forum about the format of a package). Where can I find the documentation inside Max, typing "Packages" in the search field of the File-Broswer give me no result?
Share
Klangschmied
Sep 12 2017 | 10:17 am
Answering my question: I found the doc via "search documentation" in the patcher window.
Share
Jeff Kaiser
Sep 12 2017 | 10:09 pm
Thanks, Timothy, very helpful!
Share
davebeckford
Sep 13 2017 | 11:39 pm
Thanks, Timothy, quite timely....
is there a way to report packages installed at runtime?
Share
davebeckford
Sep 23 2017 | 5:52 pm
I think i came up with a solution that works. the goal was to test to see if a package is installed and load it into toplevel patch . I ended up using absolute path to test if a file from the package is visible to max, if not ,the default component is loaded
Share

Timothy Place

Sep 23 2017 | 7:51 pm

Hi Dave -- There is an interface to Packages in JS which may not be documented...

For example:

// search in the interfaces folder of C74 and packages folder
function findQLookupFiles()
{
	var p = new Packages;
	var paths = p.getsubpaths("interfaces", 1);

	foundQLookupFiles = new Array();// clear to start fresh

	if (typeof(paths) == "string")	// just one file
		lookForQLookup(paths);
	else {							// array of files, you do use third party, how cool is that ;-)
		for (var i = 0; i < paths.length; i++) {
			lookForQLookup(paths[i]);
		}
	}	
}

Roman Thilenius
Sep 24 2017 | 11:32 pm
lots of text for an information which could probably be explained with much less noise.
i still lack some things:
- please what is the complete list of allowed folder names (snippets? media?) - wether (or how) i can have custom named folders outside as well as inside the search path. (imagine a folder for pictures which are shared between helpfiles and abstractions)
- if you install a package from a local source, will it be able to overwrite the currently installed version?
Share
Rob Ramirez
Sep 25 2017 | 6:06 pm
- please what is the complete list of allowed folder names (snippets? media?)
https://docs.cycling74.com/max7/vignettes/packages
Share
Roman Thilenius
Sep 26 2017 | 3:37 am
ah there, danke. this page managed it to hide from me for years.
Share
Roman Thilenius
Sep 26 2017 | 7:37 am
i thought one can install from a local .zip too but it doesnt seem to work. or am i too stupid?
Share
Tj Shredder
Nov 06 2017 | 3:04 pm
In my installation of Max (7.3.5) my packages do not show up in the package manager. I started out with placing my St.ools collection into there quite a while ago, they never showed up. Is there a setting in Max which prevents that? Edit: I just realized, that the labeling "Show All" and "Installed" is completely misleading. "Installed" shows my custom packages, where as "Show All" only shows the "official" ones installed or not installed... I expected, that "Show All" would show all (as the words imply) including the installed ones... Maybe Max 8 could make it clearer...;-)
Share
Timothy Place
Nov 06 2017 | 4:29 pm
Note that sometimes there can be confusion as well here if you have a different package name in your "package-info.json" file as compared to the name of the folder.
Share
klaus filip
May 17 2019 | 11:22 pm
hi tim and all, i need to include third party-externals in my package (yes, ppooll). is there a way to find out, if these externals already exist in another package installed? for example i have a bunch of jasch externals and i would like to disable(hide) the ones in my package, if the jasch package is installed and active. thanks klaus
Share
Timothy Place
Jul 18 2019 | 8:33 pm
Hi Klaus,
I don't really see how this will be possible. For example, in addition to needing to move files on the disk in and out of the searchpath, after doing so a re-launch of Max will be required. There is certainly no mechanism built-in to our tools to do this and doing it on your own would be very challenging as well.
Packages with dependencies on other packages is a tricky game indeed.
Share
Roman Thilenius
Jul 19 2019 | 2:53 am
i wonder if one could let user install a little file - or enter an url - for an "allow to install packages from these sites" option in a future update of max.
this way third parties could make use of the package manager while the user can choose one by one which updates he want to see.
Share
csaudiodesign
May 14 2020 | 2:04 pm
Hi Tim, I was using the JS code you suggested to list subfolder contents of packages quit a lot, very handy: ( https://cycling74.com/tutorials/package-authoring-an-introduction/replies/1#reply-59c69f4dceae7a241fe343f0 ). Recently I noticed, that Packages::getsubpaths() does not return an array if there are multiple folders with the specific name in different packages. Has there been some change to the Packages() object? Also, is there any documentation to this specific object/class that you could provide? Are there other methods besides getsubpaths()?
Thanks a lot and best regards, Cedric
Share
Timothy Place
Jun 26 2020 | 3:33 pm
Hi,
I'm not sure if I follow the problem 100%. Is it possible to give a description of the folder names and packages in question? Also curious what platform and version of Max you are using. If you send this into support@cycling74.com and include my name in the email then I can help you there too.
Cheers! Tim
Share
ingmar rheinhausen
May 09 2022 | 7:38 am
Question: Do packages have any influence on the possibility to unlock a patcher? Sometimes I have difficulties to unlock a patcher, but I cannot always reproduce it. I do not want to pollute this thread, but say… are you aware of a relevant effect here?
Share