---

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 on Ghub.

For more information on the high-level process of deploying a tool, refer to Ghub tool development workflow

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 Ghub

1. On Ghub, log in, access your 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 Ghub tool directory structure, refer to this Knowledge Base article

2. Upload the working source file (example.c) into ~/apps/toolname/test/ on Ghub.

To upload, you can:

• sftp from your local machine to theghub.org, using your Ghub password. You will automatically be in your home directory on Ghub. Use the put command to transfer your source file.

• Alternately, use webdav

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 Ghub Workspace.

Create the Tool on Ghub

3. From My Account on Ghub, click My Contributions:Start a new contribution, then Tools. Fill in the page called Create New Tool, then click Register Tool. The tool's Short Name will be used to identify it on Ghub.

This series of steps creates a subversion repository for the Tool.

Prepare the Repository

4. From the Ghub Workspace, check out the Subversion directory structure into ~/apps/toolname/repo. From the ~/apps/toolname directory:

$ svn checkout https://theghub.org/tools/toolname/svn/trunk repo

This command creates the correct directory structure for the Tool.

Run Rappture Builder

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 ~/apps/toolname/repo/rappture directory, issue the commands:

$ use rappture
$ rappture -builder

Populate the GUI

6. 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.

7. 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.

8. When the tool is populated, click Save As. From the dialog, select:

• Tool Definition File
• Skeleton Program
• Makefile

The default save path for these files is the rappture/ directory. Instead, save the Makefile and Skeleton Program in src/. Accept the default file names and Tool Definition File path, and click Save.

Rappture builder will save the following:

• main.c (Skeleton Program; default name of the generated C program with inputs/outputs as indicated)
• tool.xml (Tool Definition File; default name of tool definition file used to make the GUI)
• Makefile (file with instructions for the C compiler)

Edit the Rappture Files

9. In Ghub’s Workspace xterm, edit (e.g. with vi) the following files:

main.c

Rappture’s generated source code. Its default name is main.c. This should be saved in src/. Add functional code for your tool, using the names of input and output variables, under “Add your code here…” section.

tool.xml

Rappture’s generated tool.xml. This should be saved in rappture/. Ensure it points to the bin/ directory where the executable will reside. For instance, if your executable is called mainc, edit command to read:

@tool/../bin/mainc @driver

Makefile

Rappture’s generated Makefile. This should be saved in src/. Ensure that it installs the executable in bin/. Add whatever compile targets you like; clean, distclean, install, etc.

For example, to install the compiled executable, mainc, in bin/, add the following target:

install: mainc
	install --mode 755 $< -D ../bin

 

invoke

You may also want to look at 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

10. In Ghub’s Workspace xterm, build and run the program by issuing the command from the src/ directory:

$ make install

This creates your executable and installs it in bin/. To run it using the Rappture front end, issue the following command 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. Test, troubleshoot, and patch as needed.

Invoke

To test the tool using the invoke script that Ghub 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

11. Check the working tool in to the Ghub repository using Subversion:

• add all new files and their paths to Subversion, using the command svn add. For example:

$ svn add src/main.c src/Makefile rappture/tool.xml

• Commit all files to the Subversion repository, using the command:

$ svn commit

When prompted, add a remark to Subversion describing the initial versions of the uploaded source files.

12. In the tool’s Contribtool page, set its status as Uploaded. The administrator will Install it for testing in the Ghub application area.

The Ghub application area for your tool is found at the following location in the Workspace filesystem:

/apps/toolname

These subdirectories are readable by the tool developer, and invoke calls can be issued there for troubleshooting.

Rappture References

• Rappture xml reference

• Rappture C API

• Example: Rappture and Python