= Compiling and linking user-defined code = 
[[TracNav(doc/userint/toc)]]

Users can add their own (modified) user-interface to a PALM-run by carrying out the following steps:\\\\
   1. Copy the appropriate default (empty) user-interface files {{{user_***.f90}}} to a directory of your choice, e.g.:
{{{
cd ~/palm/current_version
mkdir -p USER_CODE/example
cp trunk/SOURCE/user_***.f90  USER_CODE/example
}}}
      '''Attention: do not change the filenames! '''

   2. Set an additional path in the configuration file .mrun.config to allow mrun to find and include these files:
{{{
%add_source_path   $base_directory/USER_CODE/$fname
}}}
      The default configuration file ({{{trunk/SCRIPTS/.mrun.config.default}}}) already includes this setting.\\
   3. Modify the interface routines according to your needs.\\
   4. Start a PALM run by executing
{{{
mrun -d example ...
}}}
      The files {{{user_***.f90}}} will be automatically compiled within the job and will replace the respective {{{PALM}}}‘s default user-interface routines.\\\\

The above method with including {{{$fname}}} in the additional source path allows to use different user-interfaces for different runs at the same time. Just store the respective interface-files in subdirectories {{{USER_CODE/abcd}}}, {{{USER_CODE/cdef}}}, etc. and start '''mrun''' with option "{{{-d abcd}}}", "{{{-d cdef}}}", etc. \\\\
If the user wants to add additional routines, he/she can a) put them into the default user-interface file {{{user_additional_routines.f90}}} or b) can create new files in the additional source directory. These files must have names different from the default {{{PALM}}} source code files. In case of b), the user must also copy the default makefile into the additional source directory:
{{{
cp trunk/SOURCE/Makefile  USER_CODE/example
}}}
The makefile must be modified appropriately following the "make"-rules in order to allow the new files to be compiled.\\\\
'''The modified user-interface files cannot be pre-compiled by using mbuild! '''\\\\
While programming user-defined code, errors are frequently made. For possible ways of error tracing see [../../intdbg Debugging]. 

In case you are calling MPI functions or external functions from your user code, you might get error messages during the namelist file check, which is performed before your job is started. These errors will not occur during your model run, so you might skip the parameter file check in this case. The better option, however, is to exclude these calls from this check. In order to achieve this, can set the preprocessor directive {{{__check}}} whereever needed. 

'''Example:'''
{{{
#if ! defined ( __check )
CALL MPI_ALLREDUCE(...)
#endif
}}}