Create a Ghub Tool with Rappture Builder

by Jeanette Sperhac

Search

Search pages

Wiki

Tools

Version 10
by (unknown)
Version 11
by (unknown)

Deletions or items before changed

Additions or items after changed

1 This set of instructions takes you through creating and deploying a Ghub tool based on C code. It describes how to use the Rappture builder to quickly create a GUI to deploy your tool onto Ghub.
2
3 -
For more information on the high-level process of deploying a tool, refer to [/topics/vHUBtooldevelopmentworkflow Ghub tool development workflow]
+
For more information on the high-level process of deploying a tool, refer to [/topics/GhubToolDevelopmentWorkflow Ghub tool development workflow]
4
5 ==Create the Code==
6 1. Develop a program (e.g. `example.c`) that accepts inputs and generates
7 outputs. Compile and test it on your local machine.
8
9 ===Upload and Test on Ghub===
10 2. Log into Ghub and access your [/tools/workspace Workspace], and click Launch Tool. In the Workspace `xterm`, organize your home directory in the following way, by creating directories:
11 {{{
12 ~/apps/toolname/
13 test/ - useful for testing basic tool code
14 in this phase of dev
15 repo/ - houses the local svn repository
16 (checked-out code version)
17 }}}
18
19 For more information on the Hub tool directory structure, refer to [/explore/topics/GhubToolDirectoryStructure Ghub Tool Directory Structure]
20
21
22 3. Upload the working source file (`example.c`) into `~/apps//test/` on Ghub.
23
24 To upload, you can:
25 * `sftp` from your local machine to Ghub using your Ghub password. You will automatically be in your home directory on Ghub. Use the `put` command to transfer your source file.
26
27 * Alternately, use [/support/knowledgebase/tips/webdav webdav]
28
29 Compile and test the basic tool in the Ghub Workspace. Now that your code is uploaded, most of your tool creation work will take place in the Hub Workspace.
30
31 ==Prepare the Repository==
32 4. From the Ghub Workspace, check out the Subversion directory structure into `~/apps//repo`. From the `~/apps//` directory:
33 {{{
34 $ svn checkout https://theghub.org/tools/toolname/svn/trunk repo
35 }}}
36 This command creates the [/explore/topics/GhubToolDirectoryStructure correct directory structure] for the Tool.
37
38 [[Anchor(rappture-builder)]]
39 ==Run Rappture Builder==
40 5. On Ghub, access your Workspace and click 'Launch Tool'. In the Workspace `xterm`, run Rappture in builder mode. This lets you use the Rappture GUI to generate a GUI for your own program. From your `~/repo/rappture/` directory, run:
41 {{{
42 $ rappture -builder
43 }}}
44
45 ===Populate the GUI===
46 6. In the Rappture GUI, under Tool Interface, select 'tool'. Enter a Title and Description, and
47 'select the appropriate programming language from the pull-down Program menu'. This will instruct Rappture about which files to create.
48
49 7. Populate the Tool Interface Input and Output sections. Do this by dragging controls from
50 the left-hand palette and dropping them into the right hand panel. Rename the controls to match the names of your inputs and outputs; update the Label and Description fields.
51
52 8. When the tool is populated, click 'Save As'. From the dialog, select:
53 * Tool Definition File
54 * Skeleton Program
55 * Makefile
56 Choose names for these files as appropriate. Click Save.
57
58 Rappture builder will save the following:
59 * `main.c` (default name of the generated C program with inputs/outputs as indicated)
60 * `tool.xml` (default name of tool definition file used to make the GUI)
61 * `Makefile` (file with instructions for the C compiler)
62
63 [[Anchor(edit)]]
64 ===Edit the Rappture Files===
65 9. In Ghub's Workspace `xterm`, edit (e.g. with `vi`) the following files:
66
67 ====main.c====
68 Rappture's generated source code. Its default name is `main.c`. Add functional code for your tool under 'Add your code here...' section.
69
70 ====tool.xml====
71 Rappture's generated `tool.xml`. Ensure it points to the executable in the `bin/` directory.
72
73 ====Makefile====
74 Rappture's generated `Makefile`. Ensure that it installs the executable in`bin/`. Add whatever compile targets you like; `clean`, `distclean`, `install`, etc.
75
76 ====invoke====
77 You may also want to look at [http://hubzero.org/documentation/1.0.0/tooldevs/invoke middleware/invoke]. This is the invocation script for your tool itself. Ensure the script is there; it may not need any alterations.
78
79 ==Build and Test==
80 10. In Ghub's Workspace `xterm`, build and run the program (build from the `src/` directory):
81 {{{
82 $ make
83 }}}
84
85 This creates your executable. To run it using the Rappture front end, issue the following from your `rappture/` directory:
86 {{{
87 $ rappture
88 }}}
89
90 This should display the Rappture front end generated with the Rappture builder. The tool should run when you click 'Simulate'. Troubleshoot and patch as needed.
91
92 ===Invoke===
93 To test the tool using the invoke script that Ghub will use, issue the following command from your `repo/` directory:
94 {{{
95 $ ./middleware/invoke
96 }}}
97
98 Once `invoke` works, you're ready to check the tool and GUI code into Subversion.
99
100 ===Troubleshoot===
101 To troubleshoot the tool or workspace session you're running, refer to `~/data/` and its subdirectories, `sessions/` and `results/`. All user session data are written there.
102
103 ==Check in the Code and Change Status==
104 11. Check the working tool into the Ghub repository using [http://nanohub.org/resources/3064/download/subversion.pdf Subversion]:
105
106 * add all new files (`main.c`, `tool.xml`, `Makefile`, etc.) to Subversion, using the command:
107 {{{
108 $ svn add path1/name1 path2/name2
109 }}}
110 * Commit all files to the Subversion repository, using the command:
111 {{{
112 $ svn commit
113 }}}
114
115 12. In the tool's [/contribtool/ Contribtool] page, set its status as 'Uploaded'. The administrator will install it for testing in the Ghub application area.
116
117 The Ghub application area for your tool is found at:
118 {{{
119 /apps/
120 }}}
121
122 These subdirectories are readable by the tool developer, and `invoke` calls can be issued there for troubleshooting.
123
124 ==Rappture References==
125 * [https://nanohub.org/infrastructure/rappture/wiki/rappture_xml_elements Rappture xml reference]
126 * [https://nanohub.org/infrastructure/rappture/wiki/rappture_ccpp_api Rappture C API]
127 * [https://nanohub.org/infrastructure/rappture/wiki/whatIsRappture Example: Rappture and Python]