Development

• Notes for developers
• Creating a new bud

A short introduction to the buds library and how it may be extended can be found in this section.

We highly welcome suggestions, issues and/or bug-fixes. Anybody is encouraged to contribute via the github development page:

• Development repository
• Reporting issues/bugs
• Creating pull-requests for buds

Please do not hesitate to contribute!

Notes for developers

The library is heavily pasted with pre-processor statements which, sadly, is not well-supported in a large range of fortran compilers. As such we require a minimal usage of external preprocessors which adhere to the C preprocessor statements. Any development should adhere to the standards found in the already present buds. These guide-lines for the code must be followed:

• Indent in a 2-level sequence.
  • Currently this is enabled for emacs via local variables
• Pre-processor variables must adhere to these rules:
  1. Prefix with BUD_ which ensures no name-clashing with parenting libraries/applications.
  2. Ensure the implementation files contain an #undef statement to limit warnings when compiled.
• All public routines/functions must be interfaced. I.e. no routines/functions may be made public.
• Documentation using the Doxygen format for every routine. If you do not know how Doxygen works, please look in the documentation for a routine/function which you think replicates your routine the most and copy/paste the corresponding documentation.
  • Full documentation of the routine should be performed for the interface. In case several private routines are interfaced for a public routine their differences should be made clear in this documentation part.
  • Private routines should only document the parameters.
  • Create references for F2003 OO procedures to the equivalent interface.

      ...
    contains
      procedure, public :: new => new_
    end type
    
    interface new
      module procedure new_
    end interface

  • Add contribution statements in the CONTRIBUTORS.md file which ensures a resulting documentation to be short and concise. In the CONTRIBUTORS.md file you may add any information and specifics of what has been implemented by specific authors.
  • Do not use the \@date marker as it clutters the documentation.
  • Use \@opt to denote optional arguments, for instance:

    !! @param[inout] bar1 updated value
    !! @param[in] bar2 \@opt=\@null decide how bar1 calculated.
    subroutine foo(bar1, bar2)
     ..., intent(inout) :: bar1
     ..., intent(in), optional :: bar2 ! none default

  • Use \@null as replacement for optional arguments which may have no information
  • To remove routines or hidden variables from the documentation you may encompass part of the code with

    
     ... ! skipped documentation in doxygen

• Only use functions for single value retrievals. Generally subroutines have less overhead and are preferred over functions. However, functions have their usage as they have a clear intente.
• Functions should be named get\_? to enable the function name as a local variable. It also helps understanding the code in-line.

Creating a new bud

A short description of the required steps needed to create a custom bud type is listed here:

1. The first code present in the type must be

   #include "bud_utils.inc"

2. Define your internal data container. Its name must be BUD_TYPE_NAME_:

   #define bud_type_name_ bud_cc2(bud_type_name,_)

   This data container name will only be visible in the module and thus it is relatively un-important what you choose.

   We, however, recommend that you re-use the public type name with an appended _.

3. Add the common declarations:

   #include "bud_common_declarations.inc"

   This adds the common used variables such as data precisions etc.

4. Define the data container (BUD_TYPE_NAME_)

   This data type may contain anything you want but must be defined as this:

   type bud_type_name_
    <contained data>
   #include "buds_common_type_.inc"
   end type

5. Add specific interfaces that you may implement for interacting with the contained data. Ensure that you add a one-line documentation to the interfaces. Explicitly add public or private for clarity of the interfaced routines.

6. Add the common buds interfaces and routines.

   #include "buds_common.inc"

   Remark that this inclusions inserts a contains statement which forces the separation of variable/interface declarations from routine declarations.

7. Create a deletion routine which shall ensure no memory leaks. I.e. it should delete all allocatable/pointers in the BUD_TYPE_NAME_ type. This routine must be named delete_data.
8. Add any specific routines for your data type. Note that you may never expose routines directly from the module. This will ensure that name-clashes are never encountered.