<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>

  <header>
    
    <title>Apache Gump&#x2122;</title>
  <authors><person name="Sam Ruby" email="rubys@us.ibm.com"/></authors></header>

<body>

    <section><title>Getting Started</title>
    <note>
    	Apache Python Gump shares the first few steps with Traditional Gump, 
    	so start <link href="site:gettingstarted">here</link>
    </note>
    </section>

	<section><title>Select your interface</title>
	<p>
	Python Gump has two primary usage interfaces:
	</p>
	<ul>
		<li><strong>Graphic User Interface (human users)</strong><br/>
			This leverages wxPython's wxWindows
		</li>
		<li><strong>Command Line (human and automatic users, e.g. cron)</strong><br/>
			This provides the basics functions of existing gump (gen/update/build)
		</li>
	</ul>
	</section>
	
	<section><title>Graphical User Interface</title>		

	<ul>
		<li>install gump as per <link href="site:gettingstarted">here</link></li>
		<li>install (or have available) Python 2.3 <fork href="https://www.activestate.com/Products/ActivePython/">e.g ActiveState Python</fork></li>
		<li>install (or have available) <fork href="https://www.wxpython.org/">wxwindows</fork></li>
		<li>open a shell and do or something equivalent:
		</li>
	</ul>		
		<source>
SET PYTHONPATH=C:\gump\python
CD /d C:\gump\python
python gump\gui\view.py -w ..\myworkspace.xml
		</source>
		<source>
cd /gump/python
export PYTHONPATH=`pwd`
python gump/gui/view.py -w ../myworspace.xml
		</source>
	</section>
	
	<section><title>GUI Usage</title>
	<p>
If you select a project, you can walk the project dependencies in both directions, see what prereqs aren't installed, see the actual classpath and properties used in the ant builds, and see what jars a project produces.  One pane initially shows the fully expanded XML project definition (implicit dependencies added, properties resolved, etc).

You actually can run a build from this tool.  A typical scenario is to select the project that you are interested in, check the prereqs and dependencies tabs.  If a dependency failed, you can click on it to go to that project.  Press the 'run' icon to build it.  If it succeeds, press the 'back' button to return to the project you started with and repeat.

More detailed information on what is being done can be found in the console window which you can access by pressing the console icon.
	</p>
	</section>

	<section><title>Command Line Tools:</title>
	<ul>

		<li>install gump as per <link href="site:gettingstarted">here</link></li>
		<li>install (or have available) Python 2.3 <fork href="https://www.activestate.com/Products/ActivePython/">e.f ActiveState Python</fork></li>
		<li>install (or have available) <fork href="https://www.wxpython.org/">wxwindows</fork></li>
		<li>open a shell and do or something equivalent:
		</li>
	</ul>		
		<source>
SET PYTHONPATH=C:\gump\python
CD /d C:\gump\python
python gump\build.py -w ..\myworkspace.xml all
		</source>
		<source>
cd /gump/python
export PYTHONPATH=`pwd`
python gump/build.py -w ../myworkspace.xml all
		</source>
	<note>
	There are some similar tools w/ similar command line arguments:
	<br/><strong>update.py</strong> -- update project(s) from source control
	<br/><strong>build.py</strong> -- build project(s)
	<br/><strong>integrate.py</strong> -- does "the works" check/update/build/statistics/document/nag
	</note>
	<note>
	The command line arguments accept a regular expression that resolves over project names <strong>NOT</strong> module names. "all" is converted to the regular expression "*". This is a new feature in Python Gump, and a mild divergence from traditional gump usage. When (say) updating a "list of modules" the utilities calculate the modules containing the requests projects, and hence translates for the user.
	</note>
</section>
<!--
== Automating the "integration process" using integrate.py ==

* install 'regular' gump as per https://gump.apache.org/usage.html
* install [https://www.activestate.com/Products/ActivePython/ Python 2.3]
* open a shell and do something similar to:
<source>
SET PYTHONPATH=C:\gump\python
CD /d C:\gump\python
python gump\integrate.py -w ..\myworkspace.xml all
</source>
<source>
cd /gump/python
export PYTHONPATH=`pwd`
python gump/integrate.py -w ../myworkspace.xml krysalis-*
</source>

This tool is intended for use from cron, or similar scheduling software. It does:

* Reads the workspace and project information
* Performs updates (from source control)
* Performs synchronization (into build directory)
* Performs builds
* All results affect the per module/per project "state"
* State and "work" is maintained in memory and files
* Statistics (FOG Factor and others) are calculated from states & updated
* Once complete the run is "documented" by creating xdocs (for Forrest)
* Forrest is launched to convert this documentation to a site
* Nag e-mails are sent as appropriate. [currently commented out]

See: http://lsd.student.utwente.nl/gump/
-->

</body>
</document>
