source: trunk/SRC/Documentation/xmldoc/getsaxo.xml @ 353

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article [
<!ENTITY % isolat1 SYSTEM "http://www.w3.org/2003/entities/iso8879/isolat1.ent">
%isolat1;
<!ENTITY % isolat2 SYSTEM "http://www.w3.org/2003/entities/iso8879/isolat2.ent">
%isolat2;
<!ENTITY % isogrk3 SYSTEM "http://www.w3.org/2003/entities/iso8879/isogrk3.ent">
%isogrk3;
<!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent">
%isopub;
<!ENTITY % isotech SYSTEM "http://www.w3.org/2003/entities/iso8879/isotech.ent">
%isotech;
<!ENTITY % isonum SYSTEM "http://www.w3.org/2003/entities/iso8879/isonum.ent">
%isonum;
<!ENTITY promptidl "idl&gt;">
]>
<article version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:lang="en"
xml:id="getsaxo">

  <title>Get <application>SAXO</application></title>

  <info>
    <authorgroup>
      <author><personname><firstname>Sébastien</firstname> <surname>Masson</surname></personname> <email>Sebastien.Masson_at_locean-ipsl.upmc.fr</email></author>
      <author><personname><firstname>Françoise</firstname> <surname>Pinsard</surname></personname> <email>Francoise.Pinsard_at_locean-ipsl.upmc.fr</email></author>
    </authorgroup>
    <keywordset>
      <keyword>IDL</keyword>
      <keyword>SAXO</keyword>
    </keywordset>
    <revhistory>
      <revision>
        <revnumber>0.0</revnumber>
        <date>May 2006</date>
        <revremark>First draft</revremark>
      </revision>
      <revision>
        <revnumber>0.1</revnumber>
        <date>April 2008</date>
        <revremark>migration from DocBook 4.2 to Docbook 5.0</revremark>
      </revision>
    </revhistory>
   <pubdate>$Id$</pubdate>
  </info>

  <!--  1st part -->

  <sect1 xml:id="create_saxo_env">
    <title> Create <application>SAXO</application> environment </title>
    <para>
      To simplify the explanation, we suppose that we install <application>SAXO</application> in your <filename class='directory'>${HOME}</filename>.
      We need to create 2 directories:
      <itemizedlist>
        <listitem>
         <simpara><filename class='directory'>${HOME}/SAXO_DIR</filename> that will contain the source files of <application>SAXO</application>. It should not be modified by the user to simplify later updates.
         </simpara>
        </listitem>
        <listitem>
         <simpara><filename class='directory'>${HOME}/My_IDL</filename> that will contain user personal files (including modified <application>SAXO</application> files, if needed).
         </simpara>
       </listitem>
      </itemizedlist>
    </para>
    <para>
      <screen>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter>${HOME}</parameter></userinput>
  <prompt>$</prompt> <userinput><command>mkdir</command> <parameter>My_IDL</parameter></userinput>
      </screen>
    </para>
  </sect1>

  <!--  2nd part -->

 <sect1 xml:id="get_saxo_files">
    <title> Get <application>SAXO</application> files </title>

  <!--  2.1 -->

    <sect2 xml:id="saxo_local">
      <title> If you work at IDRIS, IPSL or LOCEAN </title>
      <para>
        <application>SAXO</application> is already installed at
        <itemizedlist>
          <listitem>
           <simpara>IDRIS, on <systemitem class="systemname">rhodes</systemitem>: <filename class='directory'>/home/rech/eee/reee217/SAXO_DIR</filename>
           </simpara>
          </listitem>
          <listitem>
           <simpara>IPSL: <filename class='directory'>/home/smlod/SAXO_DIR</filename>
           </simpara>
          </listitem>
          <listitem>
           <simpara>LOCEAN: <filename class='directory'>/usr/home/smasson/SAXO_DIR</filename>
           </simpara>
         </listitem>
        </itemizedlist>
        If you can access one of theses directories, there is no need to re-install <application>SAXO</application> again! In that case, you only have to link <filename class='directory'>${HOME}/SAXO_DIR</filename> to the appropriate directory:
        <variablelist>
          <varlistentry><term>IDRIS</term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>ln</command> <option>-s</option> <parameter>/home/rech/eee/reee217/SAXO_DIR</parameter> <parameter>${HOME}/SAXO_DIR</parameter></userinput>
          </screen>
         </listitem>
          </varlistentry>
          <varlistentry><term>IPSL</term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>ln</command> <option>-s</option> <parameter>/home/smlod/SAXO_DIR</parameter> <parameter>${HOME}/SAXO_DIR</parameter></userinput>
          </screen>
           </listitem>
          </varlistentry>
          <varlistentry><term>LOCEAN</term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>ln</command> <option>-s</option> <parameter>/usr/home/smasson/SAXO_DIR</parameter> <parameter>${HOME}/SAXO_DIR</parameter></userinput>
          </screen>
           </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect2>

  <!--  2.2 -->

    <sect2 xml:id="saxo_svn">
      <title> If <link xl:href="http://subversion.tigris.org/"><application> Subversion (svn)</application></link> is installed on your machine </title>
 <!--   2.2.1 -->
      <sect3 xml:id="saxo_svn_users">
        <title> Regular users </title>
      <para>
        The <emphasis role="bold">complete</emphasis> latest revision (source + tests data files: &szallsvn; Mb) can be checked out with the following command executed in your <envar>${HOME}</envar>:
        <screen>
  <prompt>$</prompt> <userinput><command>svn</command> <option>checkout</option> <parameter>http://forge.ipsl.jussieu.fr/saxo/svn/trunk/</parameter> <parameter>SAXO_DIR</parameter></userinput>
        </screen>
      </para>
      <para>
        The latest revision of the <emphasis role="bold">source files</emphasis> (&szsrcsvn; Mb) can be checked out with the following command:
        <screen>
  <prompt>$</prompt> <userinput><command>svn</command> <option>checkout</option> <parameter>http://forge.ipsl.jussieu.fr/saxo/svn/trunk/SRC</parameter> <parameter>SAXO_DIR/SRC</parameter></userinput>
        </screen>
      </para>
      <para>
        The latest revision of the <emphasis role="bold">NetCDF data files</emphasis> (&szdatasvn; Mb) used by the test programs can be checked out with the following command:
        <screen>
  <prompt>$</prompt> <userinput><command>svn</command> <option>checkout</option> <parameter>http://forge.ipsl.jussieu.fr/saxo/svn/trunk/DATA</parameter> <parameter>SAXO_DIR/DATA</parameter></userinput>
        </screen>
      </para>
      </sect3>
<!--    2.2.2 -->
      <sect3 xml:id="saxo_svn_contributors">
        <title> Contributors </title>
      <para>
        <emphasis role="bold">Contributors</emphasis> should better use the following command (and replace login by their own login):
        <screen >
  <prompt>$</prompt> <userinput><command>svn</command> <option>checkout</option> <parameter>svn+ssh://<replaceable>login</replaceable>@forge.ipsl.jussieu.fr/ipsl/forge/projets/saxo/svn/trunk/</parameter> <parameter>SAXO_DIR</parameter></userinput>
        </screen>
      </para>
      </sect3>
    </sect2>

  <!--  2.3 -->

    <sect2 xml:id="saxo_tar">
      <title> Get <application>SAXO</application> from a tar file </title>
  <!--  2.3.1 -->
      <sect3 xml:id="saxo_src_tar">
        <title> Get <application>SAXO</application> source files (&szsrc; Mb) </title>
        <para>
          Create your <filename class='directory'>${HOME}/SAXO_DIR</filename> directory &hellip;
          <screen>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter>${HOME}</parameter></userinput>
  <prompt>$</prompt> <userinput><command>mkdir</command> <parameter>SAXO_DIR</parameter></userinput>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter>SAXO_DIR</parameter></userinput>
          </screen>
         </para>
         <para>
          &hellip; and download it the latest version of the sources tar file: <link xl:href="http://forge.ipsl.jussieu.fr/saxo/download/SAXO_SRC_&date;.tar.gz">SAXO_SRC_&date;.tar.gz</link> (&szsrc; Mb).
</para>
<para>
This tar.gz file could also be downloaded with <command>wget</command> or <command>curl</command>
        <variablelist>
          <varlistentry><term><command>wget</command></term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>wget</command> <parameter>http://forge.ipsl.jussieu.fr/saxo/download/SAXO_SRC_&date;.tar.gz</parameter></userinput>
          </screen>
           </listitem>
          </varlistentry>
          <varlistentry><term><command>curl</command></term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>curl</command> <option>-O</option> <parameter>http://forge.ipsl.jussieu.fr/saxo/download/SAXO_SRC_&date;.tar.gz</parameter></userinput>
          </screen>
           </listitem>
          </varlistentry>
        </variablelist> 
        Untar the file
        <screen>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter>${HOME}/SAXO_DIR</parameter></userinput>
  <prompt>$</prompt> <userinput><command>tar</command> <option>xvfz</option> <parameter>SAXO_SRC_&date;.tar.gz</parameter></userinput>
  <prompt>$</prompt> <userinput><command>rm</command> <parameter>SAXO_SRC_&date;.tar.gz</parameter></userinput>
        </screen>
        </para>

      </sect3>
  <!--  2.3.2 -->
      <sect3 xml:id="saxo_data_tar">
        <title> Get <application>SAXO</application> tests data files (&szdata; Mb) </title>
        <para>
        If you want to use the tests programs, you need to download the data tests files (<filename>SAXO_DATA_&date2;.tar.gz</filename>), you may download theses files in
        <itemizedlist>
          <listitem>
           <simpara><filename class='directory'>${HOME}/My_IDL</filename>. This is the easiest solution but it could be inconvenient if your <envar>${HOME}</envar> disk space is limited.
           </simpara>
          </listitem>
          <listitem>
           <para>any other directory of your choice. In that case, when using IDL, you will need to define the variable <varname>iodir</varname> to the directory you choose in order to let IDL find the data tests files. This can be done either through the <filename>init.pro</filename> file (see <xref linkend="generate_init"/>) or directly within IDL with the following command: <prompt>&promptidl;</prompt> <userinput><command>iodir = <replaceable>the chosen directory</replaceable></command></userinput>.
           </para>
          </listitem>
        </itemizedlist>
        <screen>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter>${HOME}</parameter></userinput>
  <prompt>$</prompt> <userinput><command>mkdir</command> <parameter><replaceable>CHOSEN_DIR</replaceable></parameter></userinput>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter><replaceable>CHOSEN_DIR</replaceable></parameter></userinput>
        </screen>
        Download <link xl:href="http://forge.ipsl.jussieu.fr/saxo/download/SAXO_DATA_&date2;.tar.gz">SAXO_DATA_&date2;.tar.gz</link> (&szdata; Mb)
        or with <command>wget</command> or <command>curl</command> &hellip;
        <variablelist>
          <varlistentry><term><command>wget</command></term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>wget</command> <parameter>http://forge.ipsl.jussieu.fr/saxo/download/SAXO_DATA_&date2;.tar.gz</parameter></userinput>
          </screen>
           </listitem>
          </varlistentry>
          <varlistentry><term><command>curl</command></term>
          <listitem><screen>
  <prompt>$</prompt> <userinput><command>curl</command> <option>-O</option> <parameter>http://forge.ipsl.jussieu.fr/saxo/download/SAXO_DATA_&date2;.tar.gz</parameter></userinput>
          </screen>
            </listitem>
          </varlistentry>
        </variablelist>
        </para>
      </sect3>
    </sect2>
  </sect1>
  <!--  3 -->
    <sect1 xml:id="generate_init">
      <title> Generate your init.pro file </title>
      <para>
        To use <application>SAXO</application>, we need to build an IDL script that we usually call "<filename>init.pro</filename>". This file contains a set of IDL commands and default definitions (paths and variables of the common files) that are necessary to <application>SAXO</application>. Once it has been created, <filename>init.pro</filename> should the first executed command when starting IDL session.
      </para>
      <para>
        <screen>
  <prompt>$</prompt> <userinput><command>cd</command> <parameter>${HOME}/SAXO_DIR/SRC</parameter></userinput>
  <prompt>$</prompt> <userinput><command>idl</command></userinput>
  <computeroutput>IDL Version 6.0, Mac OS X (darwin ppc m32). (c) 2003, Research Systems, Inc.</computeroutput>
<!--
  <computeroutput>Installation number: 35411.</computeroutput>
  <computeroutput>Licensed for personal use by Jean-Philippe BOULANGER only.</computeroutput>
  <computeroutput>All other use is strictly prohibited.</computeroutput>
-->
  <prompt>&promptidl;</prompt> <userinput><command>buildinit</command></userinput>
  <computeroutput>% Compiled module: BUILDINIT.</computeroutput>
        </screen>
</para>
<para>
        You must then answer several questions:
<!--    <itemizedlist mark='opencircle'> -->
        <itemizedlist>
          <listitem>
           <simpara>give the path of <filename class='directory'>${HOME}/My_IDL</filename></simpara>
          </listitem>
          <listitem>
           <simpara>give the path of <filename class='directory'>${HOME}/SAXO_DIR</filename></simpara>
          </listitem>
          <listitem>
           <simpara>compatibility with the old version: No (except if you want to use old programs)</simpara>
          </listitem>
          <listitem>
           <simpara>give a default path for the data directory</simpara>
          </listitem>
          <listitem>
           <simpara>give a default path for the postscript directory</simpara>
          </listitem>
          <listitem>
           <simpara>give a default path for the images directory</simpara>
          </listitem>
          <listitem>
           <simpara>give a default path for the animation directory</simpara>
          </listitem>
          <listitem>
           <simpara>number of accessible printer and their configuration</simpara>
          </listitem>
          <listitem>
           <simpara>default color table</simpara>
          </listitem>
          <listitem>
           <simpara>default page orientation (portrait/landscape)</simpara>
          </listitem>
          <listitem>
           <simpara>default page size</simpara>
          </listitem>
          <listitem>
           <simpara>default window size</simpara>
          </listitem>
          <listitem>
           <simpara>postscript archiving options</simpara>
          </listitem>
          <listitem>
           <simpara>name of the init file (<filename>init.pro</filename>)</simpara>
          </listitem>
        </itemizedlist>
</para>
<para>
        <screen>
   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
   <computeroutput>% Compiled module: XMANAGER.</computeroutput>
   <computeroutput>% Compiled module: LOADCT.</computeroutput>
   <computeroutput>% Compiled module: FILEPATH.</computeroutput>
   <computeroutput>% Compiled module: PATH_SEP.</computeroutput>
   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
   <computeroutput>% Compiled module: STRSPLIT.</computeroutput>
   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
   <computeroutput>% Compiled module: CW_FIELD.</computeroutput>
   <prompt>&promptidl;</prompt> <userinput><command>exit</command></userinput>
        </screen>
</para>
<para>
        There is an example of the kind of <link xl:href="idlfiles/init_example.pro"> <filename>init.pro</filename></link> you should get.
      </para>
    </sect1>
<sect1 xml:id="aftergetsaxo">
<title>After this</title>
<para>
You are now ready to do your
<link xl:href="./firststeps.html">First steps with SAXO</link>.
</para>
</sect1>
</article>