Creating a New Package Workbook
The Maple Workbook is a project file that is capable of storing a Maple package, its source code, and all related help documentation. This guide will walk you through how to create a Maple package workbook.
Creating a New Package
Making a New Package Workbook
Adding Supplementary Materials
Adding a Package Workbook to the MapleCloud Packages Group
A package is a collection of routines that provide a range of functionality for solving problems in some well-defined problem domain. The scope of a package may be quite wide or very small. There are numerous built-in packages in Maple; for a complete list see index,packages.
This guide assumes that you have already created code for a Maple package module. For more resources that discuss authoring packages, see:
Writing Packages (Maple Programming Guide)
Implementing Packages using Modules
Creating Package-Specific Context Menus
An example package workbook can be found here.
After you have created a new package, the first step in creating a package workbook is to savelib your package into a workbook file.
Creating a New Workbook
To begin, you need to create a new workbook file to store your package and any supplementary code.
First, open a new worksheet and Save As Workbook. Give this workbook a name that is similar to your package name. For this example, call this file PackageWorkbook.maple.
You can also programmatically create a new workbook file to store your package code using PackageTools:-Create command.
PackageTools:-Create( cat( currentdir(), "/PackageWorkbook.maple" ) );
The next step is to save this package into your new workbook file. Most Maple packages are written in either a Maple worksheet or in a supplementary text file.
Reading an External Text File into Your Workbook
If you have written your package in an external text file, say MyPackage.mpl, you can save this into the current workbook using the following commands:
The following reads in your package, loading the package into Maple's memory:
read( "this:///Source.mpl" );
This can then be saved into the current workbook using:
savelib( 'TestModule', cat( currentdir(), "/PackageWorkbook.maple" ) );
The line above uses a filepath to the location of the Workbook on disk. It is also possible to save the package using a reference to the Workbook itself:
savelib( 'TestModule', "this://" );
Saving a Package Stored in a Maple Worksheet
If your package has been authored in a Maple worksheet, then you can simply:
Load the package into memory:
with(TestModule):
Or
After you have saved your package into the workbook, save the workbook and you have created a new Package Workbook!
Creating a package is really just the first step. In order for others to get the most out of your work or to collaborate with you on your projects, you need to share documentation and source code.
You can add content to your workbook using the Workbook Navigator or programmatically using the PackageTools:-AddAttachment command.
PackageTools:-AddAttachment( "PackageWorkbook.maple", cat( kernelopts(datadir), "/images/start/Folder_default.png" ) ):
Adding an Overview Page
It is very important to add an overview page that introduces your package and shows users how to use it. It is always possible to add more documentation (see the section below), but adding an overview page is essential.
It is recommended that you add the following details to the top of any overview page:
Package Name
Package Summary (Short)
Author
Author Contact Details (Optional)
Following that, you can add an introduction, examples, and any other supplementary material that you want to share.
Adding Documentation
It is recommended that every command in your package has a help page with examples. These help pages can be collected in the Workbook Navigator tree under the help folder.
In order to add your help pages (and overview page) to the Maple help system, you need to build the help pages into a help database and include this in your help folder. Details on building a new help database can be found on the makehelp page.
Note that the PackageTools:-Install command will automatically extract .help files from a workbook and add these to the toolbox installation folder.
Adding Source Code
It is usually recommended to share your source code in your workbook file. Place your source code in a folder called lib in the Workbook Navigator tree.
You can always hide attachments in the Workbook Navigator tree for advanced users. For more information, see worksheet,workbook,password.
Adding Images
Images, such as an icon for your package can be added to the images folder.
Adding System Files
If your package has any required system files such as *.dll or *.so files, add them to a bin.$SYS folder. When a workbook package is installed that contains any such files, those files are extracted to the bin.$SYS folder of the toolbox installation path.
Windows
Any required DLL files must be added to the following folder in the Workbook tree:
bin.X86_64_WINDOWS
MacOS
Any required SO files must be added to the following folder in the Workbook tree:
bin.APPLE_UNIVERSAL_OSX
Linux
bin.X86_64_LINUX
Note: You will need to restart Maple after the installation of a package with extracted system library files.
The MapleCloud provides access to numerous user contributed packages. After you have finished creating a package workbook, uploading can be done as follows:
Open your workbook.
Go to the File menu and select Save to Cloud.
A dialog box appears where you can enter details about your package. It is important to try and add as much detail as possible to this dialog so that others can more easy find out more about your work. For more information see worksheet,cloud,metadata.
Make sure to set the value of Application Type to MaplePackage.
When you are done, click Publish and the package is added to the MapleCloud.
For further details on uploading content to the MapleCloud, see worksheet,cloud,upload.
Choosing a Title for Your Package
Naming commands and packages is often one of the most difficult tasks. When naming a package:
Try to give it a unique name.
Avoid using any version numbers in the name unless it is relevant to the functionality.
Try to avoid conflicts with existing packages in Maple.
Note that any newly installed packages are "post-pended" to Maple's library path. This means that any existing libraries will take precedence over the new package; that's why having a unique name is important!
Updating an Existing Package
If you make any changes to your package and want to publish those changes, simply open your updated workbook and save it to the MapleCloud. If you saved your workbook on first submission, the MapleCloud will detect your metadata and automatically update the existing file.
If for some reason the metadata was not saved into your workbook and you cannot update the existing file, try to download a copy of your workbook from the MapleCloud and make the changes in the downloaded file instead. The downloaded file will have all of the MapleCloud metadata included. For more details on querying or setting package properties, see "Scripting Packages" below.
Scripted Packages
It is possible to programmatically create a package workbook using the Create command. If you have constructed a script that recreates your package whenever you make updates to the source, you will also need to programmatically add metadata to the package workbook.
In this case, the GetProperty and SetProperty commands from the PackageTools package are useful. For example, to query and set the current unique identifier for a cloud package:
PackageTools:-GetProperty( "this://", "X-CloudId" );
PackageTools:-SetProperty( cat( currentdir(), "/PackageWorkbook.maple" ), "X-CloudId", % );
Similarly to get and set the author id property:
PackageTools:-GetProperty( "this://", "X-CloudXId" );
PackageTools:-SetProperty( cat( currentdir(), "/PackageWorkbook.maple" ), "X-CloudXId", % );
Note that after the first submission of a package, it is necessary to manually set the "X-CloudId" and "X-CloudXId" properties when updating a package - these two properties are required for the update mechanism. Additional metadata properties can also be added in a similar programmatic way or using the cloud upload dialog.
For more on available metadata properties, see Adding Metadata to Your Package Workbook.
Collaboration
Note that all MapleCloud submissions have a unique identifier that is linked to your Maplesoft community account. At this time, it is not possible for others to modify your MapleCloud submissions. In the case that you want to collaborate on package projects, we recommend that you do so using external code project sites, such as GitHub, where you can collaborate on writing code. The original submitter can then consolidate changes into the shared MapleCloud submission.
Download Help Document
