Skip to content

Commit 2e10fce

Browse files
aparrishaparrish
committed
command line tutorial
1 parent 35d4d40 commit 2e10fce

4 files changed

Lines changed: 389 additions & 0 deletions

File tree

‎Tutorials/command-line/imgs/command-line.jpg‎

12.2 KB
Loading

‎Tutorials/command-line/index.html‎

Lines changed: 377 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,377 @@
1+
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2+
3+
<html>
4+
<head>
5+
<meta name="generator" content=
6+
"HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.12), see www.w3.org">
7+
8+
<title></title>
9+
</head>
10+
11+
<body>
12+
<h1>Processing.py on the command line</h1>
13+
14+
<table width="656">
15+
<tr>
16+
<td>
17+
<p class="license">This tutorial is for Processing's Python Mode.
18+
If you see any errors or have comments, please <a href=
19+
"https://github.com/processing/processing-docs/issues?state=open">
20+
let us know</a>. This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc-sa/4.0/"> Creative Commons
21+
Attribution-NonCommercial-ShareAlike 4.0 International License.</a> </p>
22+
23+
24+
<p>&nbsp;</p>
25+
<p>Most of the material online about Processing.py is oriented to Python Mode,
26+
which allows you to write Processing sketches in the PDE using the Python
27+
programming language. But Processing.py also provides a way for you to write
28+
and launch sketches from the command line.</p>
29+
30+
<p>Why use the command line? The PDE is great, of course, and many people use
31+
it for writing interactive applications from sketch to finished product. But
32+
there are some scenarios in which you might want to use the command line: for
33+
easier integration with collaborative version control tools; for more control
34+
over how your application gets packaged; for easier interoperability with other tools that
35+
live on the command-line; etc. Or maybe (like me) you just prefer working on
36+
the command line to working in a GUI. Whatever your reason, this tutorial will
37+
show you how to get up and running.</p>
38+
39+
<p>These instructions are tested on OSX El Capitan, but should work on other
40+
platforms as well.</p>
41+
42+
<h2 id="requirements">Requirements</h2>
43+
44+
<p>In order to run Processing.py from the command line, you'll need to <a
45+
href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">install
46+
the Java JRE</a>. Ensure that you can run Java by typing the following on
47+
the command line:</p>
48+
49+
<pre><code>$ java -version</code></pre>
50+
51+
<p>You should see some output that looks like this:</p>
52+
53+
<pre><code>java version &quot;1.8.0_92&quot;
54+
Java(TM) SE Runtime Environment (build 1.8.0_92-b14)
55+
Java HotSpot(TM) 64-Bit Server VM (build 25.92-b14, mixed mode)</code></pre>
56+
57+
<p>You'll also need to obtain the standalone version of Processing.py. Choose
58+
the appropriate link according to your platform:</p>
59+
60+
<ul>
61+
<li><a href="http://py.processing.org/processing.py-macosx.tgz">Mac OS X</a></li>
62+
<li>Windows: <a href="http://py.processing.org/processing.py-windows64.zip">64-bit</a>, <a href="http://py.processing.org/processing.py-windows32.zip">32-bit</a></li>
63+
<li>Linux: <a href="http://py.processing.org/processing.py-linux64.tgz">64-bit</a> <a href="http://py.processing.org/processing.py-linux32.tgz">32-bit</a></li>
64+
</ul>
65+
66+
<p>These files contain the Processing.py JAR file along with some example
67+
scripts and some utility programs for running Processing.py on its own, for
68+
various platforms. Decompress the file, making note of the location of the
69+
resulting directory.</p> <h2 id="the-basics">The basics</h2> <p>Once you've
70+
installed Java and decompressed the <code>processing-py.jar</code> file, put a
71+
copy of the <code>.jar</code> file in a new directory for your project. Now you
72+
can use your favorite text editor to write a Processing.py sketch. Here's a
73+
simple sketch you can use for testing. Copy it and paste as
74+
<code>mouse_follow.py</code>:</p>
75+
76+
<pre><code>def setup():
77+
size(400, 400)
78+
79+
def draw():
80+
background(255)
81+
fill(0)
82+
ellipse(mouseX, mouseY, 50, 50)</code></pre>
83+
84+
<p>Save the file in the same directory as the <code>.jar</code>. Open a command
85+
line session (with, e.g., Terminal on OSX or Command Prompt in Windows) and
86+
<code>cd</code> to the directory with the sketch and the
87+
<code>processing-py.jar</code> file. Now, type the following:</p>
88+
89+
<pre><code>java -jar processing-py.jar mouse_follow.py</code></pre>
90+
91+
<p>The command above runs the Java interpreter (<code>java</code>), and tells
92+
the interpreter to run the code in the given JAR. The
93+
<code>processing-py.jar</code> file contains all of Processing.py along with a
94+
little bit of code that reads and executes the Python file specified on the
95+
command line.</p>
96+
97+
<p>After typing the above and hitting return, you should see a window appear
98+
with the <code>mouse_follow.py</code> sketch up and running. Once you have that
99+
program working, you can run any Processing.py program on the command line
100+
using the same syntax. The <code>examples.py</code> folder contains a number of
101+
example scripts to get you started.</p>
102+
103+
<h3 id="if-something-goes-wrong...">If something goes wrong...</h3>
104+
105+
<p>If the window did not appear, then something went wrong. Make sure that you
106+
typed the command as specified, spaces and all (note that there's a space
107+
between <code>java</code> and <code>-jar</code> and that there's only one
108+
hyphen in the <code>-jar</code> parameter). If your error message says
109+
something like <code>'java' is not a recognized command</code> or <code>java:
110+
command not found</code>, then you may not have successfully installed Java
111+
(see previous section for further instructions).</p>
112+
113+
<p>Any syntax errors or runtime exceptions in your program will be printed to
114+
the terminal.</p>
115+
116+
<h3 id="java-command-line-parameters">Java command-line parameters</h3>
117+
118+
<p>When you run <code>java</code> on the command line, it's up to you to know
119+
which parameters to pass to the interpreter. For most simple applications of
120+
command-line Processing.py, the <code>-jar</code> parameter is probably the
121+
only parameter you'll need, but for more advanced usage you might need to dig a
122+
bit deeper into the possibilities. You can see a full list of parameters by
123+
typing <code>java -help</code>.</p>
124+
125+
<p>The most important parameters for you to know about right from the beginning
126+
are <code>-Xms</code> and <code>-Xmx</code>, which set the initial and maximum
127+
heap size, respectively. Roughly, the heap size is how much memory Java is
128+
allowed to use when running your program. If you're getting errors saying that
129+
you're out of memory, or if Java performance is poor when working with programs
130+
that load large objects into memory repeatedly, it might be worth overriding
131+
the defaults for these values by specifying them on the command line. <a
132+
href="https://github.com/processing/processing/wiki/Troubleshooting#out-of-memory-errors-javalangoutofmemoryerror">All
133+
of the advice given here in the Java Processing Wiki</a> also applies to
134+
Processing.py; <a
135+
href="http://crunchify.com/jvm-tuning-heapsize-stacksize-garbage-collection-fundamental/">here's
136+
another good starting point for adjusting these values</a>.</p>
137+
138+
<p>For example, to run Processing.py requesting a starting heap size of 256
139+
megabytes and a maximum heap size of 1 gigabyte:</p>
140+
141+
<pre><code>java -Xms256m -Xmx1024m -jar processing-py.jar </code></pre>
142+
143+
<h2 id="included-helper-scripts">Included helper scripts</h2>
144+
145+
<p>The distribution you downloaded comes with a number of &quot;helper
146+
scripts&quot; for running Processing.py on the command line. These are:</p>
147+
148+
<ul>
149+
<li><code>processing-py.app</code>: A drag-and-drop application for Mac OS X. You can run this and then drag Processing.py programs from the Finder into the window to run them.</li>
150+
<li><code>processing-py.bat</code>: A Windows batch file that launches a Processing.py program with a splash screen and default Java parameters</li>
151+
<li><code>processing-py.sh</code>: A shell script (for Linux, OS X and Cygwin) that launches a Processing.py program with a splash screen and default Java parameters</li>
152+
</ul>
153+
154+
<p>The benefit of using these programs is that you can launch them directly
155+
from your GUI's filesystem navigator without having to navigate to the
156+
appropriate directory, etc. All of these helper scripts, by default, launch a
157+
sketch called <code>workspace/example.py</code>; you can overwrite this script
158+
with your own code if you'd like.</p>
159+
160+
<h2 id="loading-media-and-other-data">Loading media and other data</h2>
161+
162+
<p>The Processing language supports several functions, like
163+
<code>loadImage()</code>, <code>loadFont()</code>, <code>loadShape()</code>,
164+
etc. that load data from the filesystem. Processing.py supports these functions
165+
as well! In order to use these functions, you need to put the data in a place
166+
where Processing can find it. If you're used to working in the Processing IDE,
167+
you've probably added external data to your sketch using the &quot;Add
168+
file...&quot; menu option. When you're using Processing.py directly from the
169+
command line, you can accomplish the same task by copying files directly.</p>
170+
171+
<p>By default, functions like <code>loadImage()</code> in Processing.py will
172+
look for the given filename in a subdirectory named <code>data</code> located
173+
in the same directory as your sketch. If the file isn't found there, it will
174+
attempt to find the file in the same directory as the sketch itself. For
175+
example, the following statement:</p>
176+
177+
<pre><code>loadImage(&quot;test.png&quot;)</code></pre>
178+
179+
<p>... will first attempt to load <code>&lt;your sketch
180+
dir&gt;/data/test.png</code>; if it's not found there, Processing will try
181+
to load <code>&lt;your sketch dir&gt;/test.png</code>.</p>
182+
183+
<p>An additional wrinkle with Processing.py is that Python's built-in
184+
<code>open()</code> function has been modified to follow these same rules. So
185+
the following statement:</p>
186+
187+
<pre><code>open(&quot;foo.txt&quot;).read()</code></pre>
188+
189+
<p>... will attempt to open a file named <code>foo.txt</code> inside a
190+
<code>data</code> subdirectory as well. (If it can't find the file in the
191+
<code>data</code> subdirectory, it will default to Python's normal behavior of
192+
looking for the file in exactly the path specified.)</p>
193+
194+
<p>Note: For compatibility purposes, and to avoid any unusual behavior when
195+
your sketch is bundled as a standalone library, we recommend keeping your
196+
external media in the <code>data</code> subdirectory.</p>
197+
198+
<h2 id="external-libraries">External libraries</h2>
199+
200+
<p>Just like Python Mode in the Processing IDE, Processing.py on the command
201+
line can make use of third-party libraries.</p>
202+
203+
<h3 id="processing-libraries">Processing libraries</h3>
204+
205+
<p>Processing (the vanilla Java version) has a <a
206+
href="http://processing.org/reference/libraries/">rich library of
207+
third-party contributed libraries</a>. The Processing IDE has a helpful
208+
&quot;Add Library&quot; feature that allows you to locate, download and use
209+
these libraries in your project using a GUI interface. Of course, on the
210+
command line, that option isn't available to you! So here's what you do:</p>
211+
212+
<ul>
213+
<li>Make a subdirectory called 'libraries' in the same directory as your sketch file.</li>
214+
<li>Download the Processing library that you want to use. Depending on the library, it can sometimes be tricky to find the right file to download. <a href="https://github.com/processing/processing/wiki/How-to-Install-a-Contributed-Library#manual-install">The Processing Wiki has good advice on how to identify the appropriate file and how to find the relevant files within that repository</a></li>
215+
<li>Extract the library's archive file (usually a ZIP file) and copy the resulting directory into the <code>libraries</code> subdirectory that you just created.</li>
216+
</ul>
217+
218+
<p>If you're having trouble locating the right file to download for a
219+
particular library, there's a helpful alternative technique. Use the Processing
220+
IDE's &quot;Add Library&quot; feature to download and install the library for
221+
use in the IDE. Then find the folder where the IDE keeps the libraries you've
222+
downloaded by going to the IDE's Preferences panel and clicking the
223+
&quot;Browse&quot; button next to the &quot;Sketchook Location&quot; field.
224+
Take a look inside the <code>libraries</code> subdirectory and you'll find all
225+
of the Processing libraries that you've added to the IDE. To add any of these
226+
libraries to your Processing.py sketch, simply copy the library's entire
227+
directory Processing.py's <code>libraries</code> subdirectory.</p>
228+
229+
<p>Once you've copied the files to the correct location, use Processing.py's <a
230+
href="http://py.processing.org/reference/add_library.html"><code>add_library()</code></a>
231+
function to import the library, putting the name of the library as a string
232+
literal as the parameter to the function call.</p>
233+
234+
<p>For example, to use the <a
235+
href="https://processing.org/reference/libraries/sound/">Processing Sound
236+
library</a>, download the ZIP file from <a
237+
href="https://github.com/processing/processing-sound/releases/tag/latest">the
238+
repository's &quot;releases&quot; page</a>. Unzipping the file should
239+
result in a directory called <code>sound</code>; copy this to the
240+
<code>libraries</code> subdirectory for your sketch. Once the files are in the
241+
right location, put this function call at the top of your sketch:</p>
242+
243+
<pre><code>add_library(&quot;sound&quot;)</code></pre>
244+
245+
<h3 id="python-code">Python code</h3>
246+
247+
<p>Use the <code>import</code> keyword to use external Python modules in your
248+
sketch. For code that you've written, the <code>import</code> keyword works the
249+
same as it does in vanilla Python: <code>import foo</code> will first attempt
250+
to load the code in <code>foo.py</code> (or a package in a subdirectory named
251+
<code>foo</code>) in the same directory as the sketch, and then will attempt to
252+
load a module with that name from the standard library.</p>
253+
254+
<p>It's important to note that Processing.py uses the pre-packaged Jython
255+
standard library, and (by default) can't see or use any of the Python libraries
256+
in your own system installation of Python. <a href="TK">See this tutorial on
257+
using Python libraries in Processing.py</a> for more information. Because
258+
Processing.py is built with Jython, it might also be helpful <a
259+
href="http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html">to
260+
consult Jython's documentation on modules and packages</a>.</p>
261+
262+
<h3 id="other-java-libraries">Other Java libraries</h3>
263+
264+
<p>Processing.py is built with Jython, which is built with Java, which means
265+
you can also regular Java libraries in your Processing.py sketches. (This is
266+
true whether you're using Python Mode in the IDE or Processing.py from the
267+
command line.) Just for starters, all of the <a
268+
href="https://docs.oracle.com/javase/8/docs/api/">Java standard API</a> is
269+
available to you; here's a sample sketch that opens a <a
270+
href="https://docs.oracle.com/javase/tutorial/uiswing/">Swing</a>
271+
window:</p>
272+
273+
<pre><code>from javax.swing import JFrame
274+
275+
def setup():
276+
size(400, 400)
277+
frame = JFrame(&quot;Simple Test&quot;, size=(200, 200))
278+
frame.setVisible(True)
279+
280+
def draw():
281+
background(0)</code></pre>
282+
283+
<p>Consult the <a
284+
href="http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html">Jython
285+
Book's chapter on modules and packages</a> for more information.</p>
286+
287+
<p>You can also use third-party Java libraries. The easiest way to do this is
288+
to download the library's JAR file and put it in the same directory as your
289+
Processing.py sketch. (The command-line launcher for Processing.py
290+
automatically adds whatever JARs it finds in the sketch's directory to Java's
291+
classpath.) A forthcoming tutorial will show a full example of using a Java
292+
library in a Processing.py sketch.</p>
293+
294+
<h2 id="command-line-parameters-and-environment-variables">Command-line parameters and environment variables</h2>
295+
296+
<p>Unfortunately, the way that the Processing.py command-line launcher is
297+
written makes it impossible to supply extra parameters to your script on the
298+
command line. As a workaround, you can use environment variables. For example,
299+
here's a sketch that reads the environment variables <code>SKETCH_WIDTH</code>
300+
and <code>SKETCH_HEIGHT</code> with Python's <code>os</code> library and uses
301+
them to initialize the size of an ellipse in the sketch:</p>
302+
303+
<pre><code>import os
304+
ellipse_size_x = int(os.environ[&#39;ELLIPSE_SIZE_X&#39;])
305+
ellipse_size_y = int(os.environ[&#39;ELLIPSE_SIZE_Y&#39;])
306+
def setup():
307+
size(400, 400)
308+
def draw():
309+
background(0)
310+
fill(255)
311+
ellipse(width/2, height/2, ellipse_size_x, ellipse_size_y)</code></pre>
312+
313+
<p>On the OS X or Linux command line, you can set the environment variables and
314+
run the sketch simultaneously by typing something like this (assuming you've
315+
put the code above in a file named <code>env_params.py</code>):</p>
316+
317+
<pre><code>$ ELLIPSE_SIZE_X=100 ELLIPSE_SIZE_Y=150 java -jar processing-py.jar env_params.py</code></pre>
318+
319+
<h2 id="moving-a-project-from-the-ide-to-the-command-line-and-vice-versa">Moving a project from the IDE to the command line (and vice versa)</h2>
320+
321+
<p>You can run any sketch you create in the Processing IDE on the command line.
322+
To do this, you'll first need to find the directory on your computer where the
323+
sketch files are using the &quot;Show Sketch Folder&quot; option in the
324+
&quot;Sketch&quot; menu of the IDE. Copy the <code>processing-py.jar</code>
325+
file to this directory and then navigate to the directory on the command line.
326+
(In OS X, the easiest way to do this is by typing <code>cd</code> in the
327+
Terminal window, followed by a space, and then dragging the folder from the
328+
Finder to the Terminal window and then hitting &quot;Return.&quot;)</p>
329+
330+
<p>After you've done this, run the Java interpreter as you would for any
331+
command-line Processing.py sketch. The filename to supply on the command line
332+
is the main <code>.pyde</code> file of the sketch. So, for example, if your
333+
sketch from the IDE is called <code>wonderful_python_sketch_yay</code> you
334+
might type the following to run the sketch from the command-line:</p>
335+
336+
<pre><code>$ java -jar processing-py.jar wonderful_python_sketch_yay.pyde</code></pre>
337+
338+
<p>If you have an existing Processing.py sketch that you wrote on the command
339+
line, it's possible to &quot;import&quot; it back into the Processing IDE. For
340+
short sketches, the easiest way to do this is probably to just copy and paste
341+
the source code into a new Processing IDE project. For more sophisticated
342+
sketches, you can create a sketch in the format the IDE expects &quot;by
343+
hand&quot; using the following steps:</p>
344+
345+
<ul>
346+
<li>Rename the main Python file of your sketch to have a `.pyde`
347+
extension.</li>
348+
<li>Make sure that the name of the directory that the `.pyde` file is in
349+
exactly matches the name of the `.pyde` file itself. (E.g., if your
350+
sketch is called `foo.pyde`, the directory it&#39;s in should be called
351+
`foo`).</li>
352+
<li>In the Processing IDE, use the `File &gt; Open` menu option and navigate to
353+
the directory with your sketch. Select the `.pyde` file and click
354+
&quot;Open.&quot;</li>
355+
</ul>
356+
357+
<h2 id="building-a-standalone-application">Building a standalone application</h2>
358+
359+
<p>The command-line version of Processing.py has had, in the past, a feature to
360+
create a standalone application bundle. Unfortunately, as of this writing <a
361+
href="https://github.com/jdf/processing.py/issues/211">this feature is
362+
broken</a> on some platforms. For now, the easiest way to create a
363+
stand-alone application with a command-line Processing.py sketch is to import
364+
it into the Processing IDE (as outlined in the previous section) and use Python
365+
Mode's &quot;Export Application&quot; feature, which works just fine.</p>
366+
367+
<p>&nbsp;</p>
368+
369+
<p class="license">This tutorial is for Processing's Python Mode.
370+
If you see any errors or have comments, please <a href=
371+
"https://github.com/processing/processing-docs/issues?state=open">
372+
let us know</a>. This work is licensed under a <a href="http://creativecommons.org/licenses/by-nc-sa/4.0/"> Creative Commons
373+
Attribution-NonCommercial-ShareAlike 4.0 International License.</a> </p>
374+
375+
</td>
376+
</tr>
377+
</table>

0 commit comments

Comments
 (0)