doc/user/tutorials/tutorial-firstscript.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 navmenu: Tutorials
   5 title: "Writing a Crunch script"
   6
   7 ...
   8
   9 h1. Writing a Crunch script
  10
  11 In this tutorial, we will write the "hash" script demonstrated in the first tutorial.
  12
  13 *This tutorial assumes that you are "logged into an Arvados VM instance":{{site.baseurl}}/user/getting_started/ssh-access.html#login, and have a "working environment.":{{site.baseurl}}/user/getting_started/check-environment.html*
  14
  15 This tutorial uses *@you@* to denote your username.  Replace *@you@* with your user name in all the following examples.
  16
  17 h2. Setting up Git
  18
  19 As discussed in the previous tutorial, all Crunch scripts are managed through the @git@ revision control system.
  20
  21 First, you should do some basic configuration for git (you only need to do this the first time):
  22
  23 <notextile>
  24 <pre><code>~$ <span class="userinput">git config --global user.name "Your Name"</span>
  25 ~$ <span class="userinput">git config --global user.email <b>you</b>@example.com</span></code></pre>
  26 </notextile>
  27
  28 On the Arvados Workbench, navigate to _Compute %(rarr)&rarr;% Code repositories._  You should see two repositories, one named "arvados" (under the *name* column) and a second with your user name.  Next to *name* is the column *push_url*.  Copy the *push_url* cell associated with your repository.  This should look like <notextile><code>git@git.{{ site.arvados_api_host }}:<b>you</b>.git</code></notextile>.
  29
  30 Next, on the Arvados virtual machine, clone your git repository:
  31
  32 <notextile>
  33 <pre><code>~$ <span class="userinput">git clone git@git.{{ site.arvados_api_host }}:<b>you</b>.git</span>
  34 Cloning into '<b>you</b>'...</code></pre>
  35 </notextile>
  36
  37 This will create an git checkout in the directory called *@you@*.
  38
  39 {% include 'notebox_begin' %}
  40 For more information about using @git@, try
  41
  42 notextile. <pre><code>$ <span class="userinput">man gittutorial</span></code></pre>
  43
  44 or <b>"click here to search Google for git tutorials":http://google.com/#q=git+tutorial</b>
  45 {% include 'notebox_end' %}
  46
  47 h2. Creating a Crunch script
  48
  49 Start by entering the *@you@* directory created by @git clone@.  Next create a subdirectory called @crunch_scripts@ and change to that directory:
  50
  51 <notextile>
  52 <pre><code>~$ <span class="userinput">cd <b>you</b></span>
  53 ~/<b>you</b>$ <span class="userinput">mkdir crunch_scripts</span>
  54 ~/<b>you</b>$ <span class="userinput">cd crunch_scripts</span></code></pre>
  55 </notextile>
  56
  57 Next, using @nano@ or your favorite Unix text editor, create a new file called @hash.py@ in the @crunch_scripts@ directory.
  58
  59 notextile. <pre>~/<b>you</b>/crunch_scripts$ <code class="userinput">nano hash.py</code></pre>
  60
  61 Add the following code to compute the md5 hash of each file in a collection:
  62
  63 <pre><code class="userinput">{% include 'tutorial_hash_script_py' %}</code></pre>
  64
  65 Make the file executable:
  66
  67 notextile. <pre><code>~/<b>you</b>/crunch_scripts$ <span class="userinput">chmod +x hash.py</span></code></pre>
  68
  69 {% include 'notebox_begin' %}
  70 The below steps describe how to execute the script after committing changes to git. To test the script locally, please see the "debugging a crunch script":tutorial-job-debug.html page.
  71
  72 {% include 'notebox_end' %}
  73
  74 Next, add the file to @git@ staging.  This tells @git@ that the file should be included on the next commit.
  75
  76 notextile. <pre><code>~/<b>you</b>/crunch_scripts$ <span class="userinput">git add hash.py</span></code></pre>
  77
  78 Next, commit your changes to git.  All staged changes are recorded into the local @git@ repository:
  79
  80 <notextile>
  81 <pre><code>~/<b>you</b>/crunch_scripts$ <span class="userinput">git commit -m"my first script"</span>
  82 [master (root-commit) 27fd88b] my first script
  83  1 file changed, 33 insertions(+)
  84  create mode 100755 crunch_scripts/hash.py</code></pre>
  85 </notextile>
  86
  87 Finally, upload your changes to the Arvados server:
  88
  89 <notextile>
  90 <pre><code>~/<b>you</b>/crunch_scripts$ <span class="userinput">git push origin master</span>
  91 Counting objects: 4, done.
  92 Compressing objects: 100% (2/2), done.
  93 Writing objects: 100% (4/4), 682 bytes, done.
  94 Total 4 (delta 0), reused 0 (delta 0)
  95 To git@git.qr1hi.arvadosapi.com:you.git
  96  * [new branch]      master -> master</code></pre>
  97 </notextile>
  98
  99 You should now be able to run your script using Crunch, similar to how we did it in the "first tutorial.":tutorial-job1.html  The field @"script_version"@ should be @you:master@ to tell Crunch to run the script at the head of the "master" git branch, which you just uploaded.
 100
 101 <notextile>
 102 <pre><code>~/<b>you</b>/crunch_scripts$ <span class="userinput">cat &gt;~/the_job &lt;&lt;EOF
 103 {
 104  "script": "hash.py",
 105  "script_version": "you:master",
 106  "script_parameters":
 107  {
 108   "input": "c1bad4b39ca5a924e481008009d94e32+210"
 109  }
 110 }
 111 EOF</span>
 112 ~/<b>you</b>/crunch_scripts$ <span class="userinput">arv job create --job "$(cat ~/the_job)"</span>
 113 {
 114  ...
 115  "uuid":"qr1hi-xxxxx-xxxxxxxxxxxxxxx"
 116  ...
 117 }
 118 ~/<b>you</b>/crunch_scripts$ <span class="userinput">arv job get --uuid qr1hi-xxxxx-xxxxxxxxxxxxxxx</span>
 119 {
 120  ...
 121  "output":"880b55fb4470b148a447ff38cacdd952+54",
 122  ...
 123 }
 124 ~/<b>you</b>/crunch_scripts$ <span class="userinput">arv keep get 880b55fb4470b148a447ff38cacdd952+54/md5sum.txt</span>
 125 44b8ae3fde7a8a88d2f7ebd237625b4f var-GS000016015-ASM.tsv.bz2
 126 </code></pre>
 127 </notextile>
 128
 129 Next, "debugging a crunch script.":tutorial-job-debug.html