For Platypus version 4.0.
June 18 2008.
Platypus is a developer tool for the Mac OS X operating system. It was first conceived in 2003 and implemented using the Carbon APIs. Today, Platypus has since gone through over a dozen versions, and is now entirely written in Objective C / Cocoa.
Platypus is free, open-source software distributed under the terms and conditions of the Free Software Foundation's GNU General Public License, version 2.0. This means the source code is freely available and you are free to modify and distribute it as you see fit, as long as it remains open.
While Platypus is free, it is the product of hundreds of hours of work over the span of several years. If you find Platypus a useful application, I ask that you please consider making a donation to support further development. I rely on donations to encourage me in adding features and making Platypus the best application it can be. I am generally also willing to add requested features in exchange for payment.
That being said, I would like to point out that while I am happy to respond to feature requests, bug reports and questions concerning Platypus that are not addressed in this document, I will not respond to questions concerning scripting and scripting languages. Productive use of Platypus assumes that you are competent in the scripting language in which you are programming. I am obliged to note this especially due to the large number of queries I have received through the years about individual scripting languages and their use. I simply do not have the time nor inclination to respond to such queries, especially as there are plenty of good tutorials for most scripting languages freely available online.
Platypus was conceived and created, and is currently maintained and developed by me, Sveinbjorn Thordarson <sveinbjornt@simnet.is>
The Platypus icon -- Hexley, the Darwin mascot -- was created by Jon Hooper, who was kind enough to grant me permission to use it. Derivative icons were created by Sveinbjorn Thordarson.
Additional thanks go to Troy Stephens, author of the IconFamily class used for icon handling in Platypus, and to Gianni Ceccarelli for contributing code concerning authenticated script execution. The OmniGroup Mac OS X Development mailing list and the Mac OS X Hints forums have been invaluable.
Finally, I am much in debt to Wilfredo Sanchez, author of DropScript, who inspired me to write Platypus in the first place.
Platypus is an application that allows you to create Mac OS X application wrappers around scripts. This means that scripts can be launched from the Mac OS X graphical user interface -- e.g. the Finder -- without requiring the script's end-user to use the UNIX command line interface. Your scripts in effect become Mac OS X applications, no different from any other.
Regular Mac OS X applications (.app) are bundles -- special folders with a directory structure within which a binary is stored, along with resources, configuration files and property lists. Platypus creates applications with a special binary that launches a specified script and captures its output. It can present this output in a number of ways (see. Output Types below).
Platypus is not a set of bindings between the Mac OS X APIs and scripting languages. It is not, in other words, a full development environment for Mac OS X and is not intended to be used to create substantial Mac OS X applications with sophisticated interaction etc. If you wish to write sophisticated Mac OS X applications, you should learn Cocoa. Platypus is NOT a substitute for learning to program the native application interfaces, and never will be.
The basic Platypus interface is pretty straightforward to use. As soon as you launch the Platypus application, you should see a window like this:
Now, open your favorite text editor, write the script you want to create an application from and save it. Then find your script in the Finder and drag it on the Platypus window, or, alternately, press the "Select.." button and locate it via navigation dialog). Now it's time to configure the application. The basic interface allows you to set the following things:
App NameHere you type in the name of the application you are about to create. Once you press the "Create" button, you will be prompted again for a name for your app. However, that will only be the name of the actual application bundle directory, so make sure you put in the proper application name here.
Script PathThis field contains the path to the script you will create the app from. You either define this manually by typing in the path, by pressing the "Select" button and selecting it in a navigation dialog or by dragging your script on to the Platypus window. Once you have selected a valid script, you can press the "Edit" button to open it in your default text editor. As of version 3.1, Platypus includes a very basic built-in text editor as the default editor. You can change this in the Preferences to use any external editor you want.
You can also press the "New" button. This will create a text file for you in Platypus' Application Support folder and open it in your default editor. The "Reveal" button reveals the script file in the Finder.
Depending on the scripting language you use, you will want to select the appropriate kind here. You can either select one of the predefined scripting languages from the the pop-up menu or type in the path to an interpreter of your own choice in the field next to the pop-up menu. When you select a script file, Platypus will automatically try to determine what kind of script it is by looking at the file suffix and shebang (#!) line. Please note that the interpreter you selected must exist on the Mac OS X system on which your script application will run. All the preset scripting language interpreters (e.g. Perl, Python, PHP, Tcl, Expect etc.) are a standard part of all Mac OS X installations.
The "Parameters" button next to the text field containing your script intepreter setting allows you to specify arguments for the script interpreter. This is discussed in the Advanced Options part of this document.
The Output pop-up button allows you to selected what the application you create will do with the output of the Script. There are four settings available:
None: If selected, your application will provide no feedback whatsoever. The application will just launch in the Dock and execute the script without opening any windows. All script output will go to STDOUT.
Progress Bar: A small window with a progress bar with a "Cancel" button will appear during the execution of the script. All script output will go to STDOUT.
Text Window:A window with a text field will be displayed. This window contains a text field which receives all output (i.e. STDOUT and STDERR) from the script. It is important to note that this text window is not an interactive terminal session, and cannot receive any kind of input from the user. It just displays the output of the script as it is being executed. The settings of the text field can be modified by pressing the "Text Settings" button. This will present an interface pane within which text font, color and size can be set.