<html>
<head>
<link rel="stylesheet" type="text/css" href="view.css" />
</head>
<body>
<div class="main_frame">
<p><a href="index.html">Home</a></p>
<h1>Using Autovala</h1>
<p>Autovala is designed as several Vala classes, so it can be embedded easily in other projects.</p>
<p>The first thing to do is to initializate the project. This is done by calling autovala in your desired project's folder with:</p>
<pre><code>    autovala init PROJECT_NAME</code></pre>
<p>This will create a <em>PROJECT_NAME.avprj</em> file, with the most basic info about your project (the format for this file will be explained later). It will also try to create the basic folders for a vala project, and will show a warning if they already exist. It will never delete a file, except the <em>CMakeLists</em> files, of course. The folder hierarchy is:</p>
<pre><code>    .
    +cmake
    +src
       +vapis
    +install
    +doc
    +po
    +data
       +icons
       +pixmaps
       +interface
       +local</code></pre>
<p>Autovala installs its own version of the CMake modules for Vala inside the <em>cmake/</em> folder, which contains a modified version that allows to work with Valadoc; but if you want to use a newer version you can always download the last oficial version from launchpad using bazaar:</p>
<pre><code>    bzr checkout lp:~elementary-apps/+junk/cmake-modules</code></pre>
<p>This will create a folder called <em>cmake-modules</em>. Inside it will be a folder called <em>cmake</em>. Copy the later to your project folder, overwriting the existing files (this will keep the files needed for Valadoc).</p>
<p>By default, Autovala will compile all the <em>.vala</em> source files located inside <em>src/</em> and its subfolders into a single binary called like the project's name. How to generate libraries or several binaries is explained in the <a href="tricks">tricks section</a>. Also, an autogenerated namespace called <em>Constants</em> will be added, with the following build constants inside:</p>
<pre><code>    public const string DATADIR         Base folder where the binary has been installed (usually /usr/share or /usr/local/share)
    public const string PKGDATADIR      Folder with data needed by the program
    public const string GETTEXT_PACKAGE GetText Domain Name
    public const string RELEASE_NAME    Project name
    public const string VERSION         Binary version</code></pre>
<p><strong>VAPIS</strong> is where you can put your custom VAPI files, when you need some for compiling your project.</p>
<p><strong>INSTALL</strong> is the folder where to build everything. More about it later.</p>
<p>As can be supposed, <strong>DOC</strong> has to contain the documentation, and <strong>PO</strong> will contain the files with translatable strings. These strings are extracted from the <em>.vala</em> and <em>.ui</em> files (the later from glade).</p>
<p><strong>DATA</strong> is where you must put things like D-Bus activation files, <em>.desktop</em> files, scripts, and so on. <strong>ICONS</strong> folder and subfolders should contain the icons (in png or svg format), and Autovala will automagically take into account its size to put them in the right place.</p>
<p><strong>INTERFACE</strong> should contain the <em>.ui</em> files from Glade.</p>
<p>Finally, <strong>LOCAL</strong> is a place where to put everything you want to get copied &quot;as-is&quot; into</p>
<pre><code>    usr/share/PROJECT_NAME/</code></pre>
<p>To know the precise rules used by AutoVala, check the <a href="Rules">rules section</a>.</p>
<p>When you are OK for the first compilation, just use Autovala to check the folders and automatically update the <em>.avprj</em> file with:</p>
<pre><code>    autovala refresh</code></pre>
<p>When using this command, Autovala will guess all the info about your project and put it in the <em>.avprj</em> file, so you can check and modify it if you want (more on that later). If everything is OK, just create the CMakeLists files from that data using:</p>
<pre><code>    autovala cmake</code></pre>
<p>Now you can go to the <strong>install/</strong> folder and type ' <em>cmake ..</em> ' to generate the makefiles for compile your project. You can also use <em>cmake .. -DBUILD_VALADOC=ON</em> to add Valadoc support; but if you are using Ubuntu 12.10, maybe you should try to compile Valadoc from scratch, because it seems to be a bug in the version shipped from Canonical (more on this in the <a href="tricks">tricks section</a>).</p>
<p>Since it's very common to call those two commands, one after the other, you can just use:</p>
<pre><code>    autovala update</code></pre>
<p>which will, first, update your <em>.avprj</em> file, and if there are no errors, will regenerate the <em>CMakeLists</em> files, all in one command.</p>
<p>If you want to remove all the automatically added lines in the project file, leaving only the manually added ones, you can use:</p>
<pre><code>    autovala clear</code></pre>
<p>These commands can be called from any of the folders or subfolders of the project, because it will search for the first <em>.avprj</em> file located in the current folder or upstream.</p>
<p>You can also use the Gedit plugin. With it, an <em>Autovala</em> entry will be added to the menu, with the following options:</p>
<ul>
<li>Open project file: this option will open the project file (<em>.avprj</em>) for the currently active source file.<br /></li>
<li>Update project: is the same than <em>autovala update</em><br /></li>
<li>Run CMake: runs <em>cmake ..</em> in the folder <em>install</em> of the current source file's project<br /></li>
<li>Build project: runs <em>make</em> in the folder <em>install</em> of the current source file's project<br /></li>
<li>Make clean: runs <em>make clean</em> in the folder <em>install</em> of the current source file's project<br /></li>
<li>Full clean: deletes all the content in the <em>install</em> folder. Needed when the number of files in the project, or the <em>.avprj</em> file is modified<br /></li>
<li>Full build: deletes the content in the <em>install</em> folder, updates the <em>.avprj</em> and <em>CMakeList.txt</em> files, and runs <em>cmake ..</em> and <em>make</em> in the folder <em>install</em>, all in one step</li>
</ul>
<p>Usually you should use <em>Build project</em> each time you modify the code, or <em>Full build</em> each time you add, remove or rename a file to the project, or modify the <em>.avprj</em> file.</p>
<p><a href="index.html">Home</a></p>
</div>
</body>
</html>
