Timothy Place

Of all the things I love about Max, one of my favorite features is certainly Packages. Using the 

 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.

: 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.

: Author reference documentation for Max.

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.

The Package Manager allows users to browse and download online content created by Cycling '74 and third party developers. Downloaded packages work instantly with no installation and can be easily disabled.
More info: https://cycling74.com/max7/

Package Manager Overview

A package is any folder located in one of these locations:

 for the most up-to-date details, including the specific path information for your operating system.

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:

Screen Shot 2017-09-08 at 10.04.25 AM.png

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:

Screen Shot 2017-09-08 at 10.13.34 AM.png

Now we can launch Max and open the Package Manager:

Screen Shot 2017-09-08 at 10.16.09 AM.png

When it opens, we can click the button in the upper-right of the window to show 

Screen Shot 2017-09-08 at 10.18.43 AM.png

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:

Screen Shot 2017-09-08 at 10.23.34 AM.png

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 

As an example, we can add the externals and the help patchers from Part 5 of the FFT series.

Screen Shot 2017-09-08 at 10.30.07 AM.png

Screen Shot 2017-09-08 at 10.30.20 AM.png

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.

Screen Shot 2017-09-08 at 10.32.45 AM.png

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.

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.

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. 

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.

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.

When it opens, we can click the button in the upper-right of the window to show Installed packages.

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 you can see, it is easy to get started making simple packages. 

Package_manager.jpg

Using the Package Manager I can easily extend Max with the incredible work done by others with a single click. I use Packages every day for organizing work on my computer, regardless of whether it will be shared or not. In this first of a series of articles, I will share some best practices and insights for authoring your own packages.

package-authoring-an-introduction

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?

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?


I found the doc via "search documentation" in the patcher window.

Answering my question:
I found the doc via "search documentation" in the patcher window.

is there a way to report packages installed at runtime?

is there a way to report packages  installed at runtime?

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

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

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

// 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]);
        }
    }    
}

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

// 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]);
		}
	}	
}

lots of text for an information which could probably be explained with much less noise.

- please what is the complete list of allowed folder names (snippets? media?)

- wether (or how) i can have custom named folders outside 

 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?

 - 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?


https://docs.cycling74.com/max7/vignettes/packages

ah there, danke. this page managed it to hide from me for years.

i thought one can install from a local .zip too but it doesnt seem to work. or am i too stupid?

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?

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...;-)

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...;-)


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.

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.

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



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.

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.

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

 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 

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()?

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.

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.

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?

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?

Package Authoring: An Introduction, Part 1