[[PageOutline]]
== How to extract and compile XIOS ==

 * svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/trunk XIOS ; cd XIOS [[BR]]

 * '''./make_xios --help''' (or ./make_xios -h) 
{{{
make_xios - installs XIOS on your architecture
make_xios [options]
options :
       [--prod] : compilation in production mode (default)
       [--dev] : compilation in development mode
       [--debug] : compilation in debug mode
       --arch arch : to choose target architecture
       [--avail] : to know available target architectures 
       [--full] : to generate dependencies and recompile from scratch
       [--use_oasis] : to use Oasis coupler
       [--doc] : to generate Doxygen documentation (not available yet)
       [--job ntasks] : to use parallel compilation with ntasks
       [--netcdf_lib 'netcdf4_par'/'netcdf4_seq' : default netcdf4_par] : choice of netcdf library
}}}

 * Known architectures : '''./make_xios --avail'''
{{{
GCC_LINUX
GCC_MACOSX
IA64_PLATINE
PW6_VARGAS
X64_CURIE
X64_HORUS
X64_TITANE
X64_TITANE_GCC
X64_TITANE_VAMPIR
X86_LOCGNU_FEDORA
X86_LOCINTEL_FEDORA
XT6_LYNX

}}}

 * Compilation
  * On an known architecture. For example : '''./make_xios --arch X64_CURIE'''
  * On an new architecture. You have to create your "arch_NEW_ARCH.fcm" and "arch_NEW_ARCH.path" files[[BR]]

 * Choice of compilation mode. As explained in the "help", there are three compilation modes :
   * [--prod] : compilation in production mode (default)
   * [--dev] : compilation in development mode
   * [--debug] : compilation in debug mode
For example : '''./make_xios --dev --arch PW6_VARGAS'''

 * Use of "arch*.env" file. "arch*.env" file is an optionnal file (used only if it exists) which allows to define a compilation evironment in order to compile XIOS server.

For example : cat arch-X64_TITANE_GCC.env
 
{{{
module unload bullxmpi
module load openmpi/1.4.2_gnu
module unload intel
module load gcc

export HDF5_INC_DIR=$WORKDIR/hdf5/include
export HDF5_LIB_DIR=$WORKDIR/hdf5_gnu/lib

export NETCDF_INC_DIR=$WORKDIR/netcdf4/include
export NETCDF_LIB_DIR=$WORKDIR/netcdf4_gnu/lib
}}}

 * Use of netcdf library. It is possible to use netcdf in parallel mode or sequential mode :
  * --netcdf_lib netcdf4_seq : only the multiple_file writing mode is available.  
  * --netcdf_lib netcdf4_par : both one_file mode and mutliple_file mode are available.

== How to run XIOS test ==

The compilation is ok. You have now two executables files in XIOS/bin directory :  
   * test_client.exe : a test client executable 
   * xios_server.exe : server executable

'''test_client''' allows to test XIOS server functionalities : http://forge.ipsl.jussieu.fr/ioserver/browser/XIOS/trunk/src/test/test_client.f90

You can play with XIOS using test_client.exe (and xios_server.exe) to run on attached mode (or server mode i.e MPMD mode) using '''XIOS/inputs/iodef.xml''' configuration file.

 * Attached mode :

{{{
<variable id="using_server" type="boolean">false</variable>

}}}

The xios library is linked to client test. The server executable is not used. The asynchroneous writing mode is not activated. The parallel writing mode (i.e one_file ) is available. 

For example on curie machine :
ccc_msub Job
with Job :


{{{
#!/usr/bin/ksh
#MSUB -r XIOS       # nom de la requete
#MSUB -o Script_Output_XIOS.000001    # nom du fichier de sortie
#MSUB -e Script_Output_XIOS.000001    # nom du fichier de sortie
#MSUB -eo
#MSUB -n 10 # reservation des processeurs pour le job
#MSUB -T 1800             # Limite temps (en secondes)
#MSUB -q standard
#MSUB -Q test
#MSUB -p gen2211

cd /ccc/scratch/cont003/dsm/p86caub/XIOS/bin
/usr/bin/time ccc_mprun ./test_client.exe

}}}

 * Server mode

{{{
 <variable id="using_server" type="boolean">true</variable>
}}}
 

The server executable is used. The asynchroneous writing mode is activated. The parallel writing mode (i.e one_file ) is available. 

For example on vargas machine :
llsubmit Job

with Job :


{{{
# Nom de la requete
# @ job_name = Jobname
# @ job_type = parallel
# Fichier de sortie standard
# @ output = Script_Output_000001
# Fichier de sortie erreur (le meme)
# @ error = Script_Output_000001
# Nombre de processus demandes
# @ total_tasks = 10
# Temps CPU max. par processus MPI hh:mm:ss
# @ wall_clock_limit = 0:10:00
# Memoire max. utilisee par processus
# @ data_limit = 3.2gb
# Memoire stack a etendre si besoin
## @ stack_limit = 0.5gb,0.5gb
# Pas d OpenMP
# @ resources = ConsumableCpus(1)
# Fin de l entete
# @ queue
# @ class = debug
 
cd /workgpfs/rech/ces/rces061/XIOS/bin
poe -pgmmodel MPMD -cmdfile ./run_file

}}}

with run_file ( this configuration will launch test_client on 8 processes and xios server on 2 processes ):


{{{
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./test_client.exe
./xios_server.exe
./xios_server.exe
}}}


 * Multiple_file mode

{{{
 <file_definition type="multiple_file">
}}}


Each client process (or server process) in attached mode (or server mode) writes its output file. 
Mode available with both "netcdf4_par" and "netcdf4_seq" as compilation options.

 * One_file mode 

{{{
<file_definition type="one_file">
}}}


Parallel writing from each client process (or server process) in attached mode (or server mode) to one file.
Mode available only with "netcdf4_par" as complation option.

== Documentation policy ==
The documentation is compliant with DOXYGEN syntax and all html documentations are automatically generated in directory doc
There are some general points which we should follow:
  * The language of documentation is English
  * Function declarations are documented with brief (one-line, one-sentence) comments and only brief comments.
  * Function definitions (inline or not) are documented with detailed comments.
Below are instructions to document codes in details

1. File
Here is the structure of the comment one developer should write to document a file (header or source). This part of comment must be at the beginning of a file, before anything else.
{{{
/*!
   \file context.hpp
   \author Yann Meurdesoif 
   \date 25 jan 2011
   \since 3 mar 2007

   \brief comment.

   next part of detailed comment
 */
}}}
  * The macro \date indicates file creation date
  * The macro \since specifies the latest modification
  * The macro \brief provides overview information of file
In case of multiple authors, the macro \authors should be used
{{{
/*!
   \file context.hpp
   \authors Yann Meurdesoif, Arnaud Caubel 
   \date 25 jan 2011
   \since 3 mar 2007

   \brief comment.

   next part of detailed comment
 */
}}}

2. Class, typedef, enum and struct
A class documentation is written just before the class declaration/definition in the
 header file with the following structure:
{{{
/*!
    \class A
    \brief comment associated to A

    next part of detailed comment associated to A
 */
class A {
...
};
}}}
For typedef, enum and struct, instead of the macro \class, the corresponding macros \typedef, \enum and \struct should be used.

3. Attributes
Simply, attributes should be commented with one of these syntaxes
{{{
class A {
  public :
    //! comment associated to i
    int i;
    double j; //!< comment associated to j
    /*!
      comment associated to k
     */
    B k;
    ...
}}}
 
4. Functions and constructors
Function declaration is documented with a brief comment, and only a brief comment. 
All of the following syntaxes, shown here for in-class function but also valid for external ones, can be used 
{{{
class A {
  public :
    ...
   //! brief comment associated to declaration of f
   void f();

   /*! 
       brief comment associated to declaration of g
    */
   void g();
   
   void h(); //!< comment associated to declaration of h
};
}}}
Functions definitions (inline or not) are documented with detailed comments.
If the declaration has not been commented first, the first line of the comment will be the
brief comment. The below syntaxes are for inline operations but valid for the other types
{{{
class A {
  public :
    B b;
    ...
   //! comment associated to definition of f
   void f() {
   ...
   }
   void g() //! comment associated to definition of g
   {
   ...
   }
   A() //! comment associated to definition of composite constructor
   : B() 
   {
   ...
   }

   /*!
      comment associated to definition of h
    */
   void h() {
   ...
   }
};
}}}

5. Arguments
Only in the case of a function definition, arguments and return value might be documented with following convention
{{{
/*!
    comment of function f
 */
int f (double d, //!< comment of d
       int i //!< comment of i
      ) {
...
}
/*!
    comment of function g
    \param [in] d comment of d
    \param [in/out] i comment of i
    \return comment of return value
 */
int g (double d, int i) {
...
}
}}}