/usr/share/doc/gnat-gps/html/The-Project-Wizard.html

<html lang="en">
<head>
<title>The Project Wizard - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Project-Handling.html#Project-Handling" title="Project Handling">
<link rel="prev" href="The-Project-Menu.html#The-Project-Menu" title="The Project Menu">
<link rel="next" href="The-Project-Dependencies-Editor.html#The-Project-Dependencies-Editor" title="The Project Dependencies Editor">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    
--></style>
</head>
<body>
<div class="node">
<a name="The-Project-Wizard"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="The-Project-Dependencies-Editor.html#The-Project-Dependencies-Editor">The Project Dependencies Editor</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="The-Project-Menu.html#The-Project-Menu">The Project Menu</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Project-Handling.html#Project-Handling">Project Handling</a>
<hr>
</div>

<h3 class="section">7.8 The Project Wizard</h3>

<p><a name="index-project-wizard-367"></a><!--  -->

<p class="noindent">The project wizard allows you to create in a few steps a new project file. 
It has a number of pages, each dedicated to editing a specific set of
attributes for the project.

   <p>The typical way to access this wizard is through the
<code>Project-&gt;New...</code> menu.

   <p>The project wizard is also launched when a new dependency is created
between two projects, through the contextual menu in the project
view.

   <p><a name="index-screen-shot-368"></a><img src="project-wizard.jpg" alt="project-wizard.jpg">

   <p>The wizard gives access to the following list of pages:

     <ul>
<li>Project type
<li>Project Naming
<li>Languages Selection
<li>Version Control System Selection
<li>Source Directories Selection
<li>Build Directory
<li>Main Units
<li>Library
<li>Naming Scheme
<li>Switches
</ul>

<!--  -->
<h4 class="subsection">7.8.1 Project Type</h4>

<!--  -->
<p class="noindent">Several types of project wizards are provided in GPS. Depending on the
information you have or your current setup, you will choose one or the
other.

     <ul>
<li>Single Project

     <p>This is likely the wizard you will use most often. It creates a project
file from scratch, and asks you for the location of source directories,
the object directory, <small class="dots">...</small>; The rest of this chapter describes this wizard
in more details

     <li>Project Tree

     <p>This wizard will attempt to create a set of one or more project files to
represent your current build environment. It will analyze what
your sources are, where the corresponding object files are, and will try
and find some possible setup for the project files (remember that a given
<samp><span class="file">.gpr</span></samp> project file can be associated with a single object directory.

     <p>This wizard might not work in all cases, but is worth a try to get you
started if you already have an existing set of sources

     <li>Convert GLIDE Project (.adp)

     <p>This wizard will help you convert a <samp><span class="file">.adp</span></samp> project file that is used
by the GLIDE environment. The same restrictions apply as above, except
that the list of source directories, object directories
and tool switches are read directly from that file.

     <li>Library Project
<a name="index-project_002c-library-369"></a>
This specialized wizard is similar to the Single Project wizard, except it
adds one extra page, the Library page. The output of the compilation of this
project is a library (shared or static), as opposed to an executable in the
case of <code>Single Project</code>.

     <li>Extending Project
<a name="index-project_002c-extending-370"></a>
This specialized wizard allows you to easily create extending projects
(see <a href="Extending-Projects.html#Extending-Projects">Extending Projects</a>).

   </ul>

<!--  -->
<h4 class="subsection">7.8.2 Project Naming</h4>

<!--  -->
<p class="noindent">This is the first page displayed by any of the wizard.

   <p>You must enter the name and location of the project to create. This
name must be a valid Ada identifier (i.e. start with a letter,
optionally followed by a series of digits, letters or
underscores). Spaces are not allowed. Likewise, reserved Ada keywords
must be avoided. If the name is invalid, GPS will display an error
message when you press the <code>Forward</code> button.

   <p>Child projects can be created from this dialog. These are project whose
name is of the form <code>Parent.Child</code>. GPS will automatically generate
the dependency to the parent project so as to make the child project
valid.

   <p>In this page, you should also select what languages the source files
in this project are written in. Currently supported languages are <code>Ada</code>,
<code>C</code> and <code>C++</code>. Multiple languages can be used for a single
project.

   <p>The last part of this page is used to indicate how the path should be
stored in the generated project file. Most of the time, this setting
will have no impact on your work. However, if you wish to edit the
project files by hand, or be able to duplicate a project hierarchy to
another location on your disk, it might be useful to indicate that
paths should be stored as relative paths (they will be relative to the
location of the project file).

<!--  -->
<h4 class="subsection">7.8.3 Languages Selection</h4>

<p><a name="index-Languages-371"></a><!--  -->

<p class="noindent">This page is used to select the programming languages used for the
sources of this project. By default, only <code>Ada</code> is selected. 
New languages can be added to this list by using XML files, see the
section on customizing GPS (see <a href="Adding-support-for-new-languages.html#Adding-support-for-new-languages">Adding support for new languages</a>).

   <p>Additionally, this page allows you to select the toolchain used when working on
your project. There you can select one of the pre-defined toolchains or scan
your system for installed toolchains. You can also manually define some of the
tools in the toolchain such as the debugger to use, the gnat driver to use or
the gnatls tool to use.

   <p>If you need to select a toolchain for a cross environment, you should have a
look at <a href="Working-in-a-Cross-Environment.html#Working-in-a-Cross-Environment">Working in a Cross Environment</a> for more info on this subject.

<!--  -->
<h4 class="subsection">7.8.4 VCS Selection</h4>

<p><a name="index-Version-Control-System-372"></a><a name="index-VCS-373"></a><!--  -->

<p class="noindent">The second page in the project wizard allows you to select which Version
Control system is to be used for the source files of this project.

   <p>GPS doesn't attempt to automatically guess what it should use, so you
must specify it if you want the VCS operations to be available to you.

   <p>The two actions <code>Log checker</code> and <code>File checker</code> are the
name and location of programs to be run just prior an actual commit of
the files in the Version Control System. These should be used for
instance if you wish to enforce style checks before a file is actually
made available to other developers in your team.

   <p>If left blank, no program will be run.

<!--  -->
<h4 class="subsection">7.8.5 Source Directories Selection</h4>

<!--  -->
<p class="noindent">This page lists and edits the list of source directories for the
project. Any number of source directory can be used (the default is to
use the directory which contains the project file, as
specified in the first page of the wizard).

   <p>If you do not specify any source directory, no source file will be
associated with the project, since GPS wouldn't know where to look for
them.

   <p>To add source directories to the project, select a directory in the
top frame, and click on the down arrow. This will add the directory to
the bottom frame, which contains the current list of source directories.

   <p>You can also add a directory and all its subdirectories recursively by
using the contextual menu in the top frame. This contextual menu also
provides an entry to create new directories, if needed.

   <p>To remove source directories from the project, select the directory in
the bottom frame, and click on the up arrow, or use the contextual
menu.

   <p>All the files in these directories that match one of the language
supported by the project are automatically associated with that
project.

   <p>The relative sizes of the top and bottom frame can be changed by
clicking on the separation line between the two frames and dragging
the line up or down.

<!--  -->
<h4 class="subsection">7.8.6 Build Directory</h4>

<p><a name="index-object-directory-374"></a><a name="index-exec-directory-375"></a><!--  -->

<p class="noindent">The object directory is the location where the files resulting from
the compilation of sources (e.g. <samp><span class="file">.o</span></samp> files) are placed. 
One object directory is associated for each project.

   <p>The exec directory is the location where the executables are put. By
default, this is the same directory as the object directory.

<!--  -->
<h4 class="subsection">7.8.7 Main Units</h4>

<p><a name="index-main-units-376"></a><!--  -->

<p class="noindent">The main units of a project are the files that should be compiled and
linked to obtain executables.

   <p>Typically, for C applications, these are the files that contain the
<code>main()</code> function. For Ada applications, these are the files that
contain the main subprogram each partition in the project.

   <p>These files are treated specially by GPS. Some sub-menus of
<code>Build</code> and <code>Debug</code> will have predefined entries for the
main units, which makes it more convenient to compile and link your
executables.

   <p>To add main units click on the <code>Add</code> button. This opens a file
selection dialog. No check is currently done that the selected file
belongs to the project, but GPS will complain later if it doesn't.

   <p>When compiled, each main unit will generate an executable, whose name
is visible in the second column in this page. If you are using a
recent enough version of GNAT (3.16 or more recent), you can change
the name of this executable by clicking in the second column and
changing the name interactively.

<!--  -->
<h4 class="subsection">7.8.8 Library</h4>

<p><a name="index-library-projects-377"></a><!--  -->

<p class="noindent">This page allows you to configure your project so that the output of
its compilation is a library (shared or static), as opposed to an
executable or a simple set of objet files. This library can then be linked
with other executables (and will be automatically if the project is imported
by another one.

   <p>You need to define the attributes in the top box to transform your project
into a library project. See the tooltips that appear when you leave your
mouse on top of the label to the left of each field.

   <p>If you define any of the attributes in the Standalone Library box, you
will compile a standalone library. This is a library that takes care of
its elaboration by itself, instead of relying on its caller to elaborate
it as is standard in Ada. You also have more control over what files make
up the public interface to the library, and what files are private to the
library and invisible from the outside.

<!--  -->
<h4 class="subsection">7.8.9 Naming Scheme</h4>

<p><a name="index-naming-scheme-378"></a><!--  -->

<p class="noindent">A naming scheme indicates the file naming conventions used in the different
languages supported by a given project. 
For example, all <samp><span class="file">.adb</span></samp> files are Ada files, all <samp><span class="file">.c</span></samp> files are
C files.

   <p>GPS is very flexible in this respect, and allows you to specify the
default extension for the files in a given programming language. GPS makes a
distinction between spec (or header) files, which generally contain
no executable code, only declarations, and body files which contain
the actual code. For languages other than Ada, this header file is
used rather than the body file when you select <code>Go To
Declaration</code> in the contextual menu of editors.

   <p>In a language like Ada, the distinction between spec and body
is part of the definition of the language itself, and you should be
sure to specify the appropriate extensions.

   <p>The default naming scheme for Ada is GNAT's naming scheme (<samp><span class="file">.ads</span></samp>
for specs and <samp><span class="file">.adb</span></samp> for bodies). In addition, a number of predefined
naming schemes for other compilers are available in the first combo box on
the page. You can also create your own customized scheme by entering a
free text in the text entries.

   <p><a name="index-screen-shot-379"></a><img src="naming-scheme.jpg" alt="naming-scheme.jpg">

   <p>For all languages, GPS accepts exceptions to this standard naming
scheme. For instance, this let you specify that in addition to using
<samp><span class="file">.adb</span></samp> for Ada body files, the file <samp><span class="file">foo.ada</span></samp> should also be
considered as an Ada file.

   <p>The list of exceptions is displayed in the bottom list of the naming
scheme editor. To remove entries from this list, select the line you
want to remove, and then press the &lt;Del&gt; key. 
The contents of the lines can be edited interactively, by
double-clicking on the line and column you want to edit.

   <p>To add new entries to this list, use the fields at the bottom of
the window, and press the update button.

   <p><a name="index-multi_002dunit-source-files-380"></a>GNAT and GPS both support Ada source files that contain multiple Ada
units (typically a single file would contain both the spec and the body
of the unit for instance). This is not a recommend approach if you can
avoid it, since that might trigger unnecessary recompilation of your
source files. Such source files are always handled as naming scheme
exceptions, and you can specify those in the editor by adding "at 1",
"at 2",<small class="dots">...</small> after the file name for either the spec, the body or
both. The digit after "at" is the index (starting at 1) of the unit
in the source file.

   <p>For instance, specifying "file.ada at 1" for the spec and "file.ada at 2"
for the body of the unit "unit" indicates that the two components of the
unit are in the same file, first the spec, followed by the body.

<!--  -->
<h4 class="subsection">7.8.10 Switches</h4>

<p><a name="Switches"></a><a name="index-switches-381"></a><!--  -->

<p class="noindent">The last page of the project wizard is used to select the
default switches to be used by the various tools that GPS calls (compiler,
linker, binder, pretty printer, <small class="dots">...</small>).

   <p><a name="index-screen-shot-382"></a><img src="switch-editor.jpg" alt="switch-editor.jpg">

   <p>This page appears as a notebook, where each page is associated with a
specific tool. All these pages have the same structure:

     <dl>
<dt><b>Graphical selection of switches</b><dd>The top part of each page contains a set of buttons, combo boxes,
entry fields, <small class="dots">...</small> which give fast and intuitive access to the most
commonly used switches for that tool.

     <br><dt><b>Textual selection of switches</b><dd>The bottom part is an editable entry field, where you can directly
type the switches. This makes it easier to move from
an older setup (e.g. Makefile, script) to GPS, by copy-pasting switches. 
</dl>

   <p>The two parts of the pages are kept synchronized at any time: clicking
on a button will edit the entry field to show the new switch; adding a
new switch by hand in the entry field will activate the corresponding
button if there is one.

   <p>Any switch can be added to the entry field, even if there is no
corresponding button. In this case, GPS will simply forward it to the
tool when it is called, without trying to represent it graphically.

<!--  -->
   </body></html>
gnat-gps-doc 5.0-6 / usr / share / doc / gnat-gps / html / The-Project-Wizard.html
