Package Authoring: An Introduction


    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.
    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.
    Go to Part 2 where we 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.

    • 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?
    • Sep 12 2017 | 10:17 am
      Answering my question: I found the doc via "search documentation" in the patcher window.
    • Sep 12 2017 | 10:09 pm
      Thanks, Timothy, very helpful!
    • Sep 13 2017 | 11:39 pm
      Thanks, Timothy, quite timely....
      is there a way to report packages installed at runtime?
    • 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
    • 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]);
      		}
      	}	
      }
    • 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?
    • Sep 25 2017 | 6:06 pm
      - please what is the complete list of allowed folder names (snippets? media?)
    • Sep 26 2017 | 3:37 am
      ah there, danke. this page managed it to hide from me for years.
    • 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?