diff --git a/INSTALL b/INSTALL.md similarity index 52% rename from INSTALL rename to INSTALL.md index 207a2837..2b9218d9 100644 --- a/INSTALL +++ b/INSTALL.md @@ -1,16 +1,13 @@ -Installation instructions -************************* +# Installation instructions {#installInstructions} -Copyright (C) 2016 Free Software Foundation, Inc. +- @ref installBasic +- @ref installAdvanced +- @ref installSettings +- @ref installFunctionality +- @ref installVendor -Copying and distribution of this file, with or without modification, -are permitted in any medium without royalty provided the copyright -notice and this notice are preserved. This file is offered as-is, -without warranty of any kind. - -Basic Installation -================== +# Basic Installation {#installBasic} Building buds is only controlled using the basic Makefiles included. Every setting for the compilation and installation can be controlled @@ -32,15 +29,14 @@ one can do To _only_ compile the shared library one should do: - make shared + make shared The installation will install either library and the basic buds include files in the PREFIX directory. -Advanced installation script -============================ +## Advanced installation {#installAdvanced} The actual control of the installation script can be fully controlled in the `setup.make` file. @@ -48,65 +44,71 @@ An assortment of pre-make files are created in the setup.makes directory. To use one of them you may link it to `setup.make`: - ln -s setup.makes/static-hard.make setup.make - make + ln -s setup.makes/static-hard.make setup.make + make which will use the settings for the static library using an aggressive optimization strategy. You may also denote the `setup.make` file using the `SETUP` flag: - make SETUP=static-hard # or - make SETUP=static-hard.make # or - make SETUP=setup.makes/static-hard.make + make SETUP=static-hard # or + make SETUP=static-hard.make # or + make SETUP=setup.makes/static-hard.make To check your current installation setup run this command: - make show + make show -Additional settings for the compiler ------------------------------------- +## Compiler settings {#installSettings} Either of these settings may be provided on the `make` command line or in `setup.make`. In the following 0 means disable while 1 means enable. -PREFIX=: - installation prefix for buds. +* PREFIX=: + + installation prefix for buds. -STATIC=1|0: - control whether the `libs` target is dependent on the `static` target +* STATIC=1|0: + + control whether the `libs` target is dependent on the `static` target -SHARED=0|1: - control whether the `libs` target is dependent on the `shared` target +* SHARED=0|1: + + control whether the `libs` target is dependent on the `shared` target + +* OPT=|debug|1|2|3: + + controls the optimization level of the compiler. + Debug is the lowest compiler options, 1 is low optimization and + 3 is the highest optimization. + +* VENDOR=gnu|intel|: + + use the settings in the vendor/.make file for the + compiler (see @ref installVendor). + +* SETUP=: -OPT=|debug|1|2|3: - controls the optimization level of the compiler. - Debug is the lowest compiler options, 1 is low optimization and - 3 is the highest optimization. + use the specified file in addition to the `setup.make` file + to control the options. The corresponding file will be included in the + makefile process right _after_ `setup.make`. -VENDOR=gnu|intel|: - use the settings in the vendor/.make file for the - compiler. +* MPI=0|1: -SETUP=: - use the specified file in addition to the `setup.make` file - to control the options. The corresponding file will be included in the - makefile process right _after_ `setup.make`. + control whether the MPI objects should also be added to the library. + This enables certain buds only available for MPI installations. -MPI=0|1: - control whether the MPI objects should also be added to the library. - This enables certain buds only available for MPI installations. +* OO=1|0: -OO=1|0: - control whether the objects are OO so that there exists both regular - procedures and the <>% calls. - This enables object oriented programming. + control whether the objects are OO so that there exists both regular + procedures and the `<>%%` calls. + This enables object oriented programming. -Controlling the library functionality -------------------------------------- +# Library functionality {#installFunctionality} There are several preprocessor flags for controlling the final buds library. Some of them extends the functionality while others @@ -117,16 +119,18 @@ Currently the preprocessor flags must be added to the CPPFLAGS variable: Add these to the CPPFLAGS controlling --DBUD_FORTRAN=: +* `-DBUD_FORTRAN=`: + This controls the fortran standard used. Currently if is 2003 or above the basic buds - will contain OO functionality as `bud%is_initd()` together + will contain OO functionality as `bud%%is_initd()` together with the direct function call `is_initd(bud)`. This is defaulted to 2003 as the majority of compiler vendors intrinsically support these extensions. --DBUD_ERROR=: +* `-DBUD_ERROR=`: + Controls whether the parent application will provide a routine for grabbing errors. This routine should be an external routine (not in a module). @@ -138,13 +142,12 @@ Add these to the CPPFLAGS controlling -Adding new vendors for compilation -================================== +# Compiler vendors {#installVendor} -The vendor/ directory contains individual files that creates -defaults for different vendors. -If you want to enable a new compiler you may copy the vendor/gnu.make -to vendor/.make and customize the flags to your liking. +The `vendor` directory contains individual files that creates +defaults for different vendors. +If you want to enable a new compiler you may copy the `vendor/gnu.make` +to `vendor/.make` and customize the flags to your liking. Once you have created the vendor file you may use the vendor by compiling using: @@ -156,5 +159,17 @@ Currently only GNU and Intel compiler vendors are supported: make VENDOR=gnu # default make VENDOR=intel -If you add a new vendor please consider contributing to buds by sending -the source. +If you add a new vendor please consider contributing to buds by adding +a [pull request][buds-pr]. + + + + + + + +[buds-pr]: https://github.com/siesta-project/buds/pulls + diff --git a/doc/CONTRIBUTORS.md b/doc/CONTRIBUTORS.md index 857b6520..7cb3b2bf 100644 --- a/doc/CONTRIBUTORS.md +++ b/doc/CONTRIBUTORS.md @@ -1,4 +1,4 @@ -# Contributors +# Contributors {#contrib} buds have been developed by the following list of people: @@ -15,4 +15,13 @@ buds have been developed by the following list of people: + Item_Array + LL_Array + SM_CSR + + SM_CSR_C + + SM_CSR0 + +# Acknowledgements {#contribAcknow} + +The basic concept of the reference counted mechanisms is inspired by +the FLIBS project by Arjen Markus as well as minor things from the PyF95 project. + +The initial draft of this library was created by Alberto Garcia. diff --git a/doc/DEV.md b/doc/DEV.md index 332f6eca..91f36c4f 100644 --- a/doc/DEV.md +++ b/doc/DEV.md @@ -1,4 +1,8 @@ -# Development of buds +# Development {#devel} + +- @ref develNotes +- @ref develNew + A short introduction to the buds library and how it may be extended can be found in this section. @@ -6,13 +10,13 @@ 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: -- [General development repository][buds] +- [Development repository][buds] - [Reporting issues/bugs][issues] - [Creating pull-requests for buds][pr] Please do not hesitate to contribute! -## Notes for developers +# Notes for developers {#develNotes} The library is heavily pasted with pre-processor statements which, sadly, is not well-supported in a large range of @@ -28,7 +32,9 @@ These guide-lines for the code __must__ be followed: - Pre-processor variables __must__ adhere to these rules: 1. Prefix with `BUD_` which ensures no name-clashing with - parenting libraries/applications. + 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. @@ -56,9 +62,9 @@ These guide-lines for the code __must__ be followed: end interface ~~~~~~~~~~~ - + Prefer to add contribution statements in the CONTRIBUTORS.md file + + 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 + 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: @@ -88,7 +94,7 @@ These guide-lines for the code __must__ be followed: function name as a local variable. It also helps understanding the code *in-line*. -## Creating a new bud +# Creating a new bud {#develNew} A short description of the required steps needed to create a custom bud type is listed here: @@ -153,12 +159,6 @@ create a custom bud type is listed here: that name-clashes are never encountered. -## Acknowledgements - -The basic concept of the reference counted mechanisms is inspired by -the FLIBS project by Arjen Markus as well as minor things from the PyF95 project. - -The initial draft of this library was created by Alberto Garcia. [buds]: https://github.com/siesta-project/buds diff --git a/doc/DOWNLOAD.md b/doc/DOWNLOAD.md new file mode 100644 index 00000000..37fd36f5 --- /dev/null +++ b/doc/DOWNLOAD.md @@ -0,0 +1,18 @@ +# Download {#download} + +The __buds__ library may be downloaded from the development Github page [here][buds-hp]. + +The current release can be found here: + +- [0.1.tar.gz][buds-currel] + +Previous releases can be found [here][buds-rels] but they are not +supported. +If you encounter any problem you _should_ first try and update to the latest version before an issue is raised at [issue-tracker][buds-issue]. + + + +[buds-hp]: https://github.com/siesta-project/buds +[buds-issue]: https://github.com/siesta-project/buds/issues +[buds-currel]: https://github.com/siesta-project/buds/archive/0.1.tar.gz +[buds-rels]: https://github.com/siesta-project/buds/releases diff --git a/doc/Doxyfile b/doc/Doxyfile index 9695802a..aaed22f1 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -780,7 +780,7 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = doc src include +INPUT = doc src include INSTALL.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/doc/README.md b/doc/README.md index 0a8ee878..161648f5 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,13 +1,39 @@ -# buds {#buds} +# Welcome to buds {#mainWelcome} -This library implements a generic interface for creating -reference counted variables which enables easy garbage-collection -for variables without worrying about copying data. +__Welcome to the documentation of buds BUDS_VERSION.__ + +# Introduction {#mainIntroduction} + +Implementation of generic interface for creating +reference counted variables. +Reference counted variables enables garbage-collection +for variables with the added benefit of never having to +dublicate data. This is useful when using data-types/objects which you do not know -when to delete because of depedencies. +when to delete because of unknown depedencies. + +## Documentation {#mainDocumentation} + +- @subpage installInstructions + - @ref installBasic + - @ref installAdvanced + - @ref installSettings + - @ref installFunctionality + - @ref installVendor + +- @subpage download + +- @subpage devel + - @ref develNotes + - @ref develNew + + +- @subpage contrib + - @ref contribAcknow + -## Generic interface {#budsGenericInterface} +## Generic interface {#budsGenericInterface} The basic buds-library adds certain files which are useful for creating custom reference counted types using a standard. buds may be installed @@ -15,7 +41,7 @@ in the most basic format which _only_ adds the interfaces for creating custom data types. buds may be used in this minimal form. -## The standard bud library {#budsStandardLibrary} +## The standard bud library {#budsStandardLibrary} In addition to the generic interfaces buds implements a selection of data-types which have been encountered in the development of a density @@ -25,7 +51,7 @@ generic interfaces. You are encouraged to scour the documentation to find possible compatible reference counted data types that you may find useful. -## Contributing {#budsContributing} +## Contributing {#budsContributing} We encourage contribution, be it data-type suggestions and/or pull-requests.