Create a Hub Tool with Rappture Builder
This set of instructions takes you through creating and deploying a Hub tool based on C code. It describes how to use the Rappture builder to quickly create a GUI to deploy your tool on the Hub.
For more information on the high-level process of deploying a tool, refer to '''TODO: Link to JMS article'''
==Create the Code==
'''0.''' Develop a program (e.g. example.c) that accepts inputs and generates
outputs. Compile and test it on your local machine.
==Upload and Test on the Hub==
'''1.''' On vhub.org, access your [https://vhub.org/tools/workspace Workspace] and click Launch Tool. In the Workspace xterm, organize your home directory in the following way, by creating directories:
{{{
~/apps/toolname/
test/ - useful for testing basic tool code
in this phase of dev
repo/ - houses the local svn repository
(checked-out code version)
}}}
For more information on the Hub tool directory structure, refer to '''TODO: Link to JMS article'''
'''2.''' Upload the working source file (example.c) into ~/apps/toolname/test/ on the Hub.
To upload, you can:
* sftp from your local machine to www.vhub.org, using your vhub password. You will automatically be in your home directory on vhub. Use the ''put'' command to transfer your source file.
* Alternately, use [https://vhub.org/support/knowledgebase/tips/webdav webdav]
Compile and test the basic tool in the vHub Workspace.
==Prepare the Repository==
'''3.''' Check out the Subversion directory structure into ~/apps/''toolname''/repo. From the ~/apps/''toolname'' directory:
{{{
$ svn checkout https://vhub.org/tools/toolname/svn/trunk repo
}}}
This command creates the correct directory structure '''TODO: link to details''' for the Tool.
==Run Rappture Builder==
'''4.''' On vhub.org, 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:
{{{
$ rappture -builder
}}}
===Populate the GUI===
'''5.''' In the Rappture GUI, under Tool Interface, select "tool". Enter a Title and Description, and
''select the appropriate programming language from the pull-down Program menu.'' This will instruct Rappture about which files to create.
'''6.''' Populate the Tool Interface Input and Output sections. Do this by dragging controls from
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.
'''7.''' When the tool is populated, click Save As. From the dialog, select:
* Tool Definition File
* Skeleton Program
* Makefile
Choose names for these files as appropriate. Click Save.
Rappture builder will save the following:
* main.c (default name of the generated C program with inputs/outputs as indicated)
* tool.xml (default name of tool definition file used to make the GUI)
* Makefile (file with instructions for the C compiler)
===Edit the Rappture Files===
'''8.''' In the hub's Workspace xterm, edit (e.g. with ''vi'') the following files:
====main.c====
Rappture's generated source code. Its default name is main.c. Add functional for your tool under "Add your code here..." section. Save main.c.
====tool.xml====
Rappture's generated tool.xml. Ensure it points to the executable in the bin/ directory.
====Makefile====
Rappture's generated Makefile. Ensure that it installs the executable in bin/. Add whatever
compile targets you like; clean, distclean, install, etc.
====invoke====
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.
==Build and Test==
'''9.''' Build and run the program (build from the src/ directory):
{{{
$ make
}}}
This creates your executable. To run it using the Rappture front end, issue the following from your
rappture/ directory:
{{{
$ rappture
}}}
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.
===Invoke===
To test the tool using the invoke script that the Hub will use, issue the following command from your
repo/ directory:
{{{
$ ./middleware/invoke
}}}
Once ''invoke'' works, you're ready to check the tool and GUI code into Subversion.
===Troubleshoot===
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.
==Check in the Code and Change Status==
'''10.''' Check the working tool in to the hub repository using [http://nanohub.org/resources/3064/download/subversion.pdf Subversion]:
* add all new files (main.c, tool.xml, Makefile, etc.) to Subversion, using the command:
{{{
$ svn add path1/name1 path2/name2
}}}
* Commit all files to the Subversion repository, using the command:
{{{
$ svn commit
}}}
'''11.''' In the tool's [https://vhub.org/contribtool/ Contribtool] page, set its status as Uploaded. The administrator will Install it for testing in the hub application area.
The Hub application area for your tool is found at:
{{{
/apps/toolname
}}}
These subdirectories are readable by the tool developer, and ''invoke'' calls can be issued there for troubleshooting.
==Rappture References==
* [https://nanohub.org/infrastructure/rappture/wiki/rappture_xml_elements Rappture xml reference]
* [https://nanohub.org/infrastructure/rappture/wiki/rappture_ccpp_api Rappture C API]
* [https://nanohub.org/infrastructure/rappture/wiki/whatIsRappture Example: Rappture and Python]