<?xml version="1.0"?> 

<!--
	description:

		"Using gexace"

	tool: "Gobo Eiffel Xace"
	copyright: "Copyright (c) 2017, Eric Bezault and others"
	license: "MIT License"
	date: "$Date$"
	revision: "$Revision$"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="gexace/usage">
<chapterinfo>
	<copyright>
		<year>2017</year>
		<holder>Eric Bezault</holder>
	</copyright>
	<author>
		<firstname>Eric</firstname><surname>Bezault</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>26 December 2017</date>
</chapterinfo>

<title>Using gexace</title>

<section><title>Command-line options</title>
<para>
The usual way to invoke <projectname>gexace</projectname> is as follows:
<blockquote>
	<filename>gexace --system=&lt;compiler&gt; &lt;xace_file&gt;</filename>
</blockquote>
This will read the Xace file <filename>&lt;xace_file&gt;</filename>, convert 
it to the kind of configuration file commonly used by the compiler specified
(e.g. ECF for <filename>ise</filename>), and write it to an output file
whose name is of the form <filename>&lt;compiler&gt;.&lt;extension&gt;</filename>
(e.g. <filename>ise.ecf</filename> or <filename>ge.xace</filename>).
Note that the input file <filename>&lt;xace_file&gt;</filename> is optional.
By default it will use <filename>system.xace</filename> when the 
<filename>--system</filename> option is specified, or <filename>library.xace</filename>
when the  <filename>--library</filename> option is specified.
</para><para>
Here is the list of options that can be used with <projectname>gexace</projectname>:
<variablelist>
	<varlistentry>
		<term>
			<filename>-h</filename>
		</term>
		<term>
			<filename>--help</filename>
		</term>
		<listitem><para>
			Print a summary of the command-line options of <projectname>gexace</projectname> and exit.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--define="NAME[=VALUE]( NAME[=VALUE])*"</filename>
		</term>
		<listitem><para>
			Define variables to be used when reading Xace files. Several variables
			can be defined with this option, separated by a space. The value of the
			variables is optional.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--system=&lt;compiler&gt;</filename>
		</term>
		<listitem><para>
			The input Xace file is expected to represent the description of an
			Eiffel system and the generated file is meant to work with the given
			compiler. The supported values for <filename>&lt;compiler&gt;</filename>
			are <filename>ise</filename> or <filename>ge</filename>.
			Note that this option cannot be used with the other options
			<filename>--library</filename> or <filename>--validate</filename>.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--library=&lt;compiler&gt;</filename>
		</term>
		<listitem><para>
			The input Xace file is expected to represent the description of an
			Eiffel library and the generated file is meant to work with the given
			compiler. The supported values for <filename>&lt;compiler&gt;</filename>
			are <filename>ise</filename> or <filename>ge</filename>.
			Note that this option cannot be used with the other options
			<filename>--system</filename> or <filename>--validate</filename>.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--format=&lt;format_name&gt;</filename>
		</term>
		<listitem><para>
			Format for the output file. The supported values are <filename>ecf</filename>
			or <filename>xace</filename>. By default, the format will be 
			<filename>ecf</filename> when the compiler specified in <filename>--system</filename>
			or <filename>--library</filename> is <filename>ise</filename>,
			and <filename>xace</filename> when the compiler is <filename>ge</filename>.
			Note that this option cannot be used with the option
			<filename>--validate</filename>.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--output=&lt;output_filename&gt;</filename>
		</term>
		<listitem><para>
			Name of output file. By default, it will be <filename>&lt;compiler&gt;.&lt;format&gt;</filename>
			(e.g. <filename>ise.ecf</filename> or <filename>ge.xace</filename>).
			Note that this option cannot be used with the option
			<filename>--validate</filename>.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--validate</filename>
		</term>
		<listitem><para>
			Check that the input file is a valid Xace file.
			Note that this option cannot be used with the other options
			<filename>--system</filename> or <filename>--library</filename>.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--shallow</filename>
		</term>
		<listitem><para>
			Do not process mounted Xace files. By default they are processed recursively
			and their clusters are included in the generated file in place of the mounted
			libraries.
		</para></listitem>
	</varlistentry>
	<varlistentry>
		<term>
			<filename>--verbose</filename>
		</term>
		<listitem><para>
			Run <projectname>gexace</projectname> in verbose mode.
		</para></listitem>
	</varlistentry>
</variablelist>
</para>
</section>

</chapter>
