[2] | 1 | <%namespace file="/message.mako" import="render_msg" /> |
---|
| 2 | |
---|
| 3 | <%! |
---|
| 4 | def inherit(context): |
---|
| 5 | if context.get('use_panels'): |
---|
| 6 | return '/webapps/community/base_panels.mako' |
---|
| 7 | else: |
---|
| 8 | return '/base.mako' |
---|
| 9 | %> |
---|
| 10 | <%inherit file="${inherit(context)}"/> |
---|
| 11 | |
---|
| 12 | <%def name="title()">Tool Help</%def> |
---|
| 13 | |
---|
| 14 | <h2>Tool Help</h2> |
---|
| 15 | |
---|
| 16 | %if message: |
---|
| 17 | ${render_msg( message, status )} |
---|
| 18 | %endif |
---|
| 19 | |
---|
| 20 | <p/> |
---|
| 21 | <div class="toolFormTitle">Creating an archive containing a tool or a suite of tools</div> |
---|
| 22 | <p> |
---|
| 23 | A tool or tool suite archive is a tar-format file (bzipped or gzipped tar are valid) |
---|
| 24 | containing all the files necessary to load the tool(s) into a Galaxy instance. |
---|
| 25 | </p> |
---|
| 26 | <h3>Tool Suite Archive</h3> |
---|
| 27 | <p> |
---|
| 28 | A tools suite must include a file named <code>suite_config.xml</code> which provides information about the id, name, |
---|
| 29 | version and description of the tool suite, as well as the id, name, version and description of each tool |
---|
| 30 | in the suite. Here is an example <code>suite_config.xml</code> file. |
---|
| 31 | </p> |
---|
| 32 | <p> |
---|
| 33 | <pre> |
---|
| 34 | <suite id="lastz_toolsuite" name="Suite of Lastz tools" version="1.0.0"> |
---|
| 35 | <description>This suite contains all of my Lastz tools for Galaxy</description> |
---|
| 36 | <tool id="lastz_wrapper_2" name="Lastz" version="1.1.0"> |
---|
| 37 | <description> map short reads against reference sequence</description> |
---|
| 38 | </tool> |
---|
| 39 | <tool id="lastz_paired_reads_wrapper" name="Lastz paired reads" version="1.0.0"> |
---|
| 40 | <description> map short paired reads against reference sequence</description> |
---|
| 41 | </tool> |
---|
| 42 | </suite> |
---|
| 43 | </pre> |
---|
| 44 | </p> |
---|
| 45 | </p> |
---|
| 46 | <p> |
---|
| 47 | New versions of the suite can be uploaded, replacing an older version of the suite, but the version attribute |
---|
| 48 | of the <suite> tag must be altered the same way that the version attribute of a single tool config must be altered |
---|
| 49 | if uploading a new version of a tool. |
---|
| 50 | </p> |
---|
| 51 | <p> |
---|
| 52 | The id, name and version attributes of each <tool> tag in the <code>suite_config.xml</code> file must exactly match the same |
---|
| 53 | attributes in each associated tool config in the archive or you will not be allowed to upload the archive. |
---|
| 54 | </p> |
---|
| 55 | <p> |
---|
| 56 | In addition to the <code>suite_config.xml</code> file, the archive must include all |
---|
| 57 | <a href="http://bitbucket.org/galaxy/galaxy-central/wiki/ToolConfigSyntax" target="_blank">tool config files</a>, |
---|
| 58 | executables, functional test data (if your tool config includes functional tests) and other files needed for each |
---|
| 59 | of the tools in your suite to function within Galaxy. See the information about single tool archives below for |
---|
| 60 | additional hints to enable ease-of-use when others download your suite of tools. |
---|
| 61 | </p> |
---|
| 62 | <p> |
---|
| 63 | For example, to package the above Lastz suite of tools: |
---|
| 64 | <pre> |
---|
| 65 | user@host:~% tar jcvf ~/Desktop/galaxy_lastz_toolsuite.tar.bz2 lastzsuite |
---|
| 66 | lastzsuite/ |
---|
| 67 | lastzsuite/README |
---|
| 68 | lastzsuite/suite_config.xml |
---|
| 69 | lastzsuite/lastz_paired_reads_wrapper.py |
---|
| 70 | lastzsuite/lastz_paired_reads_wrapper.xml |
---|
| 71 | lastzsuite/lastz_wrapper.py |
---|
| 72 | lastzsuite/lastz_wrapper.xml |
---|
| 73 | lastzsuite/lastz-distrib-1.02.00/ |
---|
| 74 | lastzsuite/lastz-distrib-1.02.00/src/ |
---|
| 75 | lastzsuite/lastz-distrib-1.02.00/src/Makefile |
---|
| 76 | lastzsuite/lastz-distrib-1.02.00/src/version.mak |
---|
| 77 | lastzsuite/lastz-distrib-1.02.00/src/lastz.c |
---|
| 78 | lastzsuite/lastz-distrib-1.02.00/src/lastz.h |
---|
| 79 | ... |
---|
| 80 | </pre> |
---|
| 81 | ~/Desktop/galaxy_lastz_tool.tar.bz2 is now ready to be uploaded. |
---|
| 82 | </p> |
---|
| 83 | <h3>Single Tool Archive</h3> |
---|
| 84 | <p> |
---|
| 85 | A single tool archive must include a |
---|
| 86 | <a href="http://bitbucket.org/galaxy/galaxy-central/wiki/ToolConfigSyntax" target="_blank">tool config file</a> |
---|
| 87 | and will probably also include a tool script. If any steps are necessary to install your tool beyond the basic |
---|
| 88 | instructions below, include a README file to provide details. If the tool (or parts of it) are written in C, |
---|
| 89 | the source code can be included (or put links to the source in the README). Do not include pre-compiled binaries |
---|
| 90 | without source since Galaxy is run on a wide variety of platforms. Also, if you are only wrapping or providing a |
---|
| 91 | Galaxy config for a tool that is not your own, be sure the license allows for redistribution before including any |
---|
| 92 | part of that tool in the archive. |
---|
| 93 | </p> |
---|
| 94 | <p> |
---|
| 95 | There are no requirements about the directory structure inside the archive, but for ease of use it's generally |
---|
| 96 | a good idea to put everything inside a sub-directory, instead of directly at the top level. |
---|
| 97 | </p> |
---|
| 98 | <p> |
---|
| 99 | For example, to package the Lastz tool's config file, Galaxy wrapper, and the C source: |
---|
| 100 | <pre> |
---|
| 101 | user@host:~% tar jcvf ~/Desktop/galaxy_lastz_tool.tar.bz2 lastz |
---|
| 102 | lastz/ |
---|
| 103 | lastz/README |
---|
| 104 | lastz/lastz_wrapper.py |
---|
| 105 | lastz/lastz_wrapper.xml |
---|
| 106 | lastz/lastz-distrib-1.02.00/ |
---|
| 107 | lastz/lastz-distrib-1.02.00/src/ |
---|
| 108 | lastz/lastz-distrib-1.02.00/src/Makefile |
---|
| 109 | lastz/lastz-distrib-1.02.00/src/version.mak |
---|
| 110 | lastz/lastz-distrib-1.02.00/src/lastz.c |
---|
| 111 | lastz/lastz-distrib-1.02.00/src/lastz.h |
---|
| 112 | ... |
---|
| 113 | </pre> |
---|
| 114 | ~/Desktop/galaxy_lastz_tool.tar.bz2 is now ready to be uploaded. |
---|
| 115 | </p> |
---|
| 116 | <h3>Editing Information, Categories, and Submitting For Approval</h3> |
---|
| 117 | <p> |
---|
| 118 | Simply uploading a tool to the Galaxy too shed will not allow other users to find and download your tool. It will |
---|
| 119 | need to be approved by an administrator before it appears in the tool list. |
---|
| 120 | </p> |
---|
| 121 | <p> |
---|
| 122 | After your archive has successfully uploaded, you will be redirected to the Edit Tool page. Provide a detailed |
---|
| 123 | description of what the tool does - this will be used by administrators to understand the tool before approving it |
---|
| 124 | for display on the site. Once approved, this information will be displayed to users who view your tool. In addition, |
---|
| 125 | the site administrators will have configured a number of categories with which you can associate your tool to make it |
---|
| 126 | easy to find by users looking to solve specific problems. Associate as many categories as are relevant to your tool. |
---|
| 127 | You may change the description and associated categories as often as you'd like until you click the "<strong>Submit for |
---|
| 128 | approval</strong>" button. Once submitted, the tool will be approved or rejected by an administrator. If the tool is |
---|
| 129 | rejected, you will see information about why it was rejected, and you can make appropriate changes to the archive and |
---|
| 130 | re-submit it for approval. When it is approved, your archive will be visible to everyone. At that point, the description |
---|
| 131 | and associated categories can only be changed by an administrator. |
---|
| 132 | </p> |
---|
| 133 | <p> |
---|
| 134 | When the tool has been approved or rejected, you may upload a new version by browsing to the tool's "View Tool" page, |
---|
| 135 | clicking the "Tool actions" menu in the upper right corner of the page, and selecting "Upload a new version" from the |
---|
| 136 | menu. |
---|
| 137 | </p> |
---|
| 138 | <hr/> |
---|
| 139 | <h3>Downloading and Installing Tools</h3> |
---|
| 140 | <p> |
---|
| 141 | A tool's download link will send you the tool archive. Once downloaded, unpack the tool on your local Galaxy instance's server: |
---|
| 142 | <pre> |
---|
| 143 | user@host:~% tar xvf galaxy_lastz_tool.tar |
---|
| 144 | ... |
---|
| 145 | user@host:~% tar zxvf galaxy_lastz_tool.tar.gz |
---|
| 146 | ... |
---|
| 147 | user@host:~% tar jxvf galaxy_lastz_tool.tar.bz2 |
---|
| 148 | ... |
---|
| 149 | </pre> |
---|
| 150 | If the archive includes a README file, consult it for installation instructions. If not, follow these basic steps: |
---|
| 151 | <ol> |
---|
| 152 | <li>Create a directory under <code>galaxy_dist/tools/</code> to house downloaded tool(s).</li> |
---|
| 153 | <li>In the new directory, place the XML and any script file(s) which were contained in the archive.</li> |
---|
| 154 | <li> |
---|
| 155 | If the tool includes binaries, you'll need to copy them to a directory on your <code>$PATH</code>. If the tool depends on |
---|
| 156 | C binaries but does not come with them (only source), you'll need to compile the source first. |
---|
| 157 | </li> |
---|
| 158 | <li>Add the tool to <code>galaxy_dist/tool_conf.xml</code>.</li> |
---|
| 159 | <li>Restart your Galaxy server process.</li> |
---|
| 160 | </ol> |
---|
| 161 | </p> |
---|
| 162 | <p> |
---|
| 163 | In the near future, we plan to implement a more direct method to install tools via the Galaxy administrator user interface instead |
---|
| 164 | of placing files on the filesystem and manually managing the <code>tool_conf.xml</code> file. |
---|
| 165 | </p> |
---|
| 166 | |
---|