You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Documentation/Documentation.html
+64-45Lines changed: 64 additions & 45 deletions
Original file line number
Diff line number
Diff line change
@@ -342,7 +342,7 @@ <h3 id="how-does-platypus-work-">How does Platypus work?</h3>
342
342
<p>Platypus creates application bundles with a special executable binary that runs a script and captures its output. The binary can be configured to present the script's text output in various ways, for example by showing a progress bar, a text view, a Status Item menu or a WebKit-based web view.</p>
343
343
<h3id="what-platypus-is-not">What Platypus is NOT</h3>
344
344
<p>Platypus is <strong>not</strong> a set of bindings between the native macOS APIs and scripting languages. It is not a full GUI development environment and is not intended for creating substantial applications with complex and dynamic user interaction. If you want to create advanced macOS applications, you should learn to program using the Cocoa APIs. Platypus is not and never will be a substitute for learning to use the native application programming interfaces.</p>
345
-
<p>That being said, you may be able to add some interactive GUI elements using something like <ahref="https://www.bluem.net/en/projects/pashua/">Pashua</a> or <ahref="#prompting-for-input-via-osascript-applescript">AppleScript</a>.</p>
345
+
<p>That being said, you may be able to add some interactive GUI elements using something like <ahref="https://github.com/BlueM/Pashua">Pashua</a> or <ahref="#prompting-for-input-via-osascript-applescript">AppleScript</a>.</p>
<p>Both Platypus and the applications it generates require <strong>macOS 11</strong> or later and are provided as <strong>64-bit ARM/Intel</strong> binaries. If you want to target macOS 10.8-10.15, use <ahref="https://sveinbjorn.org/files/software/platypus/platypus5.3.zip">version 5.4.1</a>.
348
348
If you want to target 10.6 and/or 32-bit Intel systems,
@@ -450,8 +450,10 @@ <h3 id="saving-and-loading">Saving and Loading</h3>
450
450
<p><imgsrc="images/profiles.png" width="212"></p>
451
451
<h3id="using-profiles-with-the-command-line-tool">Using Profiles with the Command Line Tool</h3>
452
452
<p>Profiles can be used with the <code>platypus</code> command line tool. This allows you to set all the settings for your application within the graphical user interface, save them as a profile and then load the settings with the command line app. This makes automation more convenient. The following command would load a profile with the command line tool and create an app from it named MyApp.app:</p>
</code></pre><p>See the command line tool man page for further details. An HTML version of the man page is <ahref="https://sveinbjorn.org/files/manpages/platypus.man.html">available here</a>.</p>
<p>See the command line tool man page for further details. An HTML version of the man page is <ahref="https://sveinbjorn.org/files/manpages/platypus.man.html">available here</a>.</p>
<p>Platypus Profiles are standard macOS <ahref="https://en.wikipedia.org/wiki/Property_list">property lists</a> in XML format. They can be edited using either a plain text editor or Xcode.</p>
457
459
<p>As of version 5.2, Platypus understands and resolves relative paths in Profiles. However, neither the Platypus app nor the command line tool <em>generate</em> relative paths, so if you want to use them in a Profile, you will have to edit it manually.</p>
@@ -477,18 +479,20 @@ <h3 id="creating-a-status-menu-app">Creating a Status Menu app</h3>
477
479
<p>Platypus-generated apps with <strong>Interface</strong> set to <strong>Status Menu</strong> show a Status Item in the menu bar when launched. When the item is pressed, a menu is opened, the script is executed and each line of output is shown as a menu item in the menu.</p>
478
480
<p>When the user selects a menu item, the script is executed again, but this time it receives the menu title as an argument. Based on whether it receives an argument, the script can thus determine whether it is being invoked to list the menu items or in order to perform some action for a selected menu item.</p>
479
481
<p>If this seems unclear, check out the following script, which is part of the MacbethMenu Example:</p>
480
-
<pre><code>#!/usr/bin/perl
481
-
482
-
# If 0 arguments, we show menu
483
-
if (!scalar(@ARGV)) {
484
-
print "Life's but a walking shadow, a poor player\n";
485
-
print "That struts and frets his hour upon the stage\n";
</code></pre><p>This script creates a Status Menu app which shows a few lines from Shakespeare's Macbeth as menu items. When selected, the title of the menu item in question is fed into the macOS speech synthesizer via <code>/usr/bin/say</code>.</p>
<p>This script creates a Status Menu app which shows a few lines from Shakespeare's Macbeth as menu items. When selected, the title of the menu item in question is fed into the macOS speech synthesizer via <code>/usr/bin/say</code>.</p>
text returned of (display dialog "$text" default answer "$default" buttons {"OK"} default button 1 with title "Riddle")
<spanclass="sx"> text returned of (display dialog "$text" default answer "$default" buttons {"OK"} default button 1 with title "Riddle")</span>
524
+
<spanclass="sx"> end tell</span>
525
+
<spanclass="sx"> }</span><spanclass="p">);</span>
526
+
<spanclass="p">}</span>
527
+
528
+
<spanclass="k">my</span><spanclass="nv">$result</span><spanclass="o">=</span><spanclass="n">dialog</span><spanclass="p">(</span><spanclass="s">"Answer to life, the universe and everything?"</span><spanclass="p">,</span><spanclass="s">"42"</span><spanclass="p">);</span>
529
+
</pre></div>
523
530
524
-
my $result = dialog("Answer to life, the universe and everything?", "42");
<p>Platypus includes many built-in examples. These can be opened via the <strong>Examples</strong> submenu of the <strong>Profiles</strong> menu. Brief explanation of each of the examples:</p>
<p>Platypus uses <ahref="https://sparkle-project.org">Sparkle</a> for updates. You can update to the latest version by selecting <strong>Check for updates...</strong> in the application menu. Future releases may or may not break your saved profiles. Consult the version change log for details.</p>
569
-
<p>The AppCast XML file is available <ahref="https://sveinbjorn.org/files/appcasts/PlatypusAppcast.xml">here</a>.</p>
575
+
<p>The AppCast XML feed is available <ahref="https://sveinbjorn.org/files/appcasts/PlatypusAppcast.xml">here</a>.</p>
570
576
<p>To get the absolutely latest development version of Platypus, you can check out the source repository on <ahref="https://github.com/sveinbjornt/Platypus">GitHub</a>.</p>
<h3id="can-i-use-platypus-to-create-proprietary-software-">Can I use Platypus to create proprietary software?</h3>
573
-
<p>Yes. Platypus is distributed under the terms and conditions of the three-clause <ahref="https://sveinbjorn.org/files/software/platypus/documentation/License.html">BSD License</a>.</p>
579
+
<p>Yes. Platypus is distributed under the terms and conditions of the three-clause <ahref="https://sveinbjorn.org/files/software/platypus/documentation/License.html">BSD License</a>.
580
+
Do what you want but keep my name out of it.</p>
574
581
<h3id="help-text-output-isn-t-being-shown-until-the-script-is-done-">Help, text output isn't being shown until the script is done!</h3>
575
582
<p>You need to autoflush the output buffer. In Python, you can pass the <code>-u</code> parameter to the interpreter to get unbuffered output, or alternately flush the output buffer in code:</p>
576
-
<pre><code>import sys
577
-
sys.stdout.flush()
578
-
</code></pre><p>In Perl, this is done with the following command at the start of your script:</p>
579
-
<pre><code>$| = 1;
580
-
</code></pre><p>For help with other scripting languages, <ahref="https://stackoverflow.com">Stack Overflow</a> is your friend.</p>
<p>Online search should be able to help you out with other scripting languages.</p>
581
592
<h3id="does-platypus-support-localizations-">Does Platypus support localizations?</h3>
582
593
<p>No. But if you uncheck "Optimize nib file" in the save dialog when creating an app, the resulting nib in the application bundle can be edited using Xcode. You can thus localize your app manually if you want to. Support for localization is not on the feature roadmap.</p>
583
594
<h3id="how-does-my-script-access-the-user-s-shell-environment-e-g-path-">How does my script access the user's shell environment (e.g. PATH)?</h3>
584
595
<p>Assuming that you're using <code>bash</code>, you can set the interpreter to <code>/bin/bash</code> and add the <code>-l</code> flag as an argument under "Args". This makes <code>bash</code> act as if it had been invoked as a login shell. See <code>man bash</code> for details.</p>
585
596
<p>Another alternative is to manually load the user's shell configuration file in your script:</p>
586
-
<pre><code>source ~/.bashrc
587
-
</code></pre><p>For other shells, consult their respective documentation.</p>
<p>For other shells, consult their respective documentation.</p>
588
601
<h3id="how-can-i-pass-specific-arguments-to-my-script-">How can I pass specific arguments to my script?</h3>
589
602
<p>You can edit arguments to both the script interpreter and the script itself by pressing the <strong>Args</strong> button next to the <strong>Interpreter</strong> controls.</p>
590
603
<h3id="how-do-i-uninstall-platypus-">How do I uninstall Platypus?</h3>
<h3id="how-do-i-get-the-path-to-my-application-and-or-bundled-files-from-within-the-script-">How do I get the path to my application and/or bundled files from within the script?</h3>
597
610
<p>The script executed by Platypus-generated applications runs from the Resources directory of the application bundle (e.g. <code>MyApp.app/Contents/Resources</code>). Any bundled files are thus accessible from the script's current working directory.</p>
598
611
<p>For example, if you have added <code>file.txt</code> as a bundled file and want to copy it over to the user's home directory using a shell script, you would run the following command:</p>
599
-
<pre><code>cp file.txt ~/
600
-
</code></pre><p>To get the path to the application bundle itself, or its containing directory, you can use <code>../..</code> (application bundle) or <code>../../..</code> (application bundle's containing directory).</p>
612
+
<divclass="highlight"><pre>cp file.txt ~/
613
+
</pre></div>
614
+
615
+
<p>To get the path to the application bundle itself, or its containing directory, you can use <code>../..</code> (application bundle) or <code>../../..</code> (application bundle's containing directory).</p>
601
616
<h3id="how-do-platypus-generated-applications-work-">How do Platypus-generated applications work?</h3>
602
-
<p>Platypus-generated applications are macOS application (.app) <ahref="https://en.wikipedia.org/wiki/Bundle_(OS_X">bundles</a>#OS_X_application_bundles), and have the following directory structure:</p>
617
+
<p>Platypus-generated applications are macOS application (.app) <ahref="https://en.wikipedia.org/wiki/Application_bundle">bundles</a>), and have the following directory structure:</p>
603
618
<pre><code>MyApp.app/ Application bundle folder
604
619
MyApp.app/Contents
605
620
MyApp.app/Contents/Info.plist Info property list for app
<h3id="is-there-a-way-to-sign-platypus-generated-apps-so-they-don-t-require-gatekeeper-approval-">Is there a way to sign Platypus-generated apps so they don't require GateKeeper approval?</h3>
623
638
<p>Platypus-generated apps are not signed by default. Due to GateKeeper, this means they will not run on macOS without prompting the user for approval. </p>
624
639
<p>Platypus apps, like any other apps, can signed using the following command:</p>
<p>See Apple's <ahref="https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Introduction/Introduction.html">Code Signing Guide</a> for details.</p>
627
644
<h3id="can-i-pass-arguments-to-a-platypus-generated-app-via-the-command-line-">Can I pass arguments to a Platypus-generated app via the command line?</h3>
628
645
<p>Yes. You can execute a Platypus-generated binary via the command line. Any arguments you provide will be passed on to your script. Take the following example:</p>
</code></pre><p>In this case, both <code>-arg1</code> and <code>-arg2</code> will be passed on as arguments to your script. This feature makes it possible to create protocol handlers for Firefox and other programs that invoke macOS application binaries from the shell.</p>
<p>In this case, both <code>-arg1</code> and <code>-arg2</code> will be passed on as arguments to your script. This feature makes it possible to create protocol handlers for Firefox and other programs that invoke macOS application binaries from the shell.</p>
631
650
<h3id="where-is-the-command-line-tool-installed-">Where is the command line tool installed?</h3>
632
651
<p>The Platypus command line tool install script creates the following files on your system:</p>
633
652
<pre><code>/usr/local/bin/platypus Program binary
@@ -639,7 +658,7 @@ <h3 id="where-is-the-command-line-tool-installed-">Where is the command line too
639
658
<h3id="can-i-customize-the-about-window-of-a-platypus-generated-app-">Can I customize the About window of a Platypus-generated app?</h3>
640
659
<p>If you add a file named <strong>Credits.rtf</strong> or <strong>Credits.html</strong> to the bundled files list, it will appear in the About window of your application.</p>
0 commit comments