Differences

This shows you the differences between two versions of the page.

--- build:configure [2016/04/08 17:59] – [Tuning configure options] Yann Pouillon
+++ build:configure [2020/08/05 16:57] (current) – [LD_LIBRARY_PATH] Jean-Michel Beuken
@@ Line 1: / Line 1: @@
 ====== Configuring the build of Abinit ======
-//Please read the [[wiki:conventions|Conventions and formatting page]] once before everything else.//
+//Please read the [[wiki:conventions|Conventions and formatting]] page at least once before everything else.//
+===== Tutorials for beginners =====
+  * {{ :build:installing_abinit.pdf |}}
 ===== The configure script =====
@@ Line 54: / Line 60: @@
 Please note that //LD_LIBRARY_PATH// is called //DYLD_LIBRARY_PATH// on MacOS.
+<WRAP important>**IMPORTANT** \\ //LD_LIBRARY_PATH// must be set **__to the same value__** both before configuring the build of Abinit and before running the corresponding executables. These 2 actions can happen at very different times, hence the risk of forgetting to set the variable again. Misconfiguring LD_LIBRARY_PATH is actually a common mistake beginners make when learning Abinit and the source of many questions asked on the [[https://forum.abinit.org/|Abinit Forums]].</WRAP>
+==== LIBRARY_PATH ====
 If you use GCC compilers, you may sometimes want to use the //LIBRARY_PATH// environment variable as well, in particular if the build fails while //LD_LIBRARY_PATH// has been correctly set. Contrary to the latter, //LIBRARY_PATH// is only used by the compiler at link-time and will be ignored when running an Abinit executable.
-<WRAP important>**IMPORTANT** \\ //LD_LIBRARY_PATH// must be set **__to the same value__** both before configuring the build of Abinit and before running the corresponding executables. These 2 actions can happen at very different times, hence the risk of forgetting to set the variable again. Misconfiguring LD_LIBRARY_PATH is actually a common mistake beginners make when learning Abinit and the source of many questions asked on the [[http://forum.abinit.org/|Abinit Forums]].</WRAP>
 ==== PYTHONPATH ====
-Python is usually installed by system administrators in a standard way on most computers. However, if you use a version of PYTHON that you have installed yourself, please make sure that the PYTHONPATH variable is properly set before configuring Abinit.
+Python is usually installed by system administrators in a standard way on most computers. However, if you use custom Python modules that you have installed yourself, please make sure that the PYTHONPATH variable is properly set before configuring Abinit.
 ==== Language-specific variables ====
@@ Line 88: / Line 96: @@
 In order to accommodate as many situations as possible, we have designed a flexible mechanism to handle config files:
   * first, the build system looks into the build directory for a config file, which lets you import parameters for a specific build;
-  * if not found, it looks into the source directory, which allows e.g. for build parameters related to a particular version of Abinit;
+  * if not found, it looks into the source directory, which allows you to use build parameters related to a particular version of Abinit;
   * if still not found, it looks into the //~/.abinit/build%%/%%// directory, which acts as a provider of default parameters corresponding to your particular preferences;
   * finally, it looks into the //%%/%%etc/abinit/build%%/%%// directory, to let system administrators provide system-wide parameters for a specific computer.
-Of these 4 possibilities, the first file encountered is processed and the build system goes on without looking for more files.
+Of these 4 possibilities, the first file encountered is processed and the build system goes on without looking for more files. In other words, config files are not cumulative. For example, if a user has a //~/.abinit/build/my_host.ac//, the system-wide defaults found in //%%/%%etc/abinit/build/my_host.ac// will always be ignored.
 Since many developers of Abinit work on shared filesystems, the build system looks by default for a file called //`hostname`.ac//, where `hostname` represents the result of the following command, that you can type in a shell to know how to name your config files (do not type the dollar signs):
@@ Line 108: / Line 116: @@
 ===== Tuning configure options =====
-<WRAP tip>**Important tip** \\ The options of //configure// are fully documented in the //~abinit/doc/build/config-template.ac// file. Even if the wiki is updated quickly to reflect the changes made to this file, there may sometimes be a slight delay before both documents are synchronized. If you find a discrepancy between the wiki and //config-template.ac//, please let us know as soon as possible so that we can fix it.</WRAP>
+<WRAP tip>**Important tip** \\ The options of //configure// are fully documented in the //~abinit/doc/build/config-template.ac// file. Even if the wiki is updated quickly to reflect the changes made to this file, there may sometimes be a slight delay before both documents are synchronized. If you find a discrepancy between the wiki and //config-template.ac//, please let us know as soon as possible so that we can fix it -- or fix it yourself if you have write permission on this wiki.</WRAP>
 The build system of Abinit is quite modular and is composed of logical blocks addressing each a specific configuration issue. The following documents will help you tune the build parameters depending on what you want to adjust.
@@ Line 121: / Line 129: @@
 //[[build:feature_triggers|Configuring feature triggers]]// provides you with useful advice on how to enhance the capabilities of Abinit with external packages.
-==== Optional features ====
-The capabilities of Abinit can be enhanced by the use of optional external packages. The corresponding options of //configure// all follow the same scheme:
-  * //enable_**package**//, to trigger the detection and build of the corresponding feature;
-  * //with_**package**//, to specify the install prefix of a package;
-  * //with_**package**_bins//, to specify where to look for the executables of a package (when applies);
-  * //with_**package**_incs//, to specify include flags when compiling code that uses the package (when applies);
-  * //with_**package**_libs//, to specify package libraries to link the code with (when applies).
-In each of the previous items, **package** will be replaced by the names listed below. Please note that the use of //with_**package**// is incompatible with the other //with_*// options, since it defines the values specified by these options in a possibly conflicting way. If you try to use both schemes, //configure// will fail and ask you to choose only one of them.
-The //with_**package**// option expects a directory as argument. For example, if you specify:
-<code>with_fox="/path/to/fox"</code>, the //configure// script will look for:
-  * binaries in ///path/to/fox/bin//;
-  * include files in ///path/to/fox/include//;
-  * libraries in ///path/to/fox/lib// and ///path/to/fox/lib64//.
-The following table summarizes the available optional features of Abinit. To enable them, you will have to make sure that the corresponding [[build:extdeps|external dependencies of Abinit]] are correctly installed on your system before configuring Abinit.
-^ Package   ^ Status       ^ Description                                    ^
-| BigDFT    | Development  | Wavelets for low-dimensional systems           |
-| ETSF_IO   | Mature       | Platform-independent data exchange             |
-| FoX       | Mature       | Fortran XML I/O                                |
-| Libpspio  | Experimental | Reading of atomic data in many formats         |
-| LibXC     | Mature       | More than 300 exchange-correlation functionals |
-| LibYAML   | Experimental | Fortran YAML I/O                               |
-| Wannier90 | Mature       | Maximally-Localized Wannier Functions (MLWFs)  |
-The following table indicates which options are allowed for each package and whether it is enabled by default. For purely optional packages, the default is to disable them, whereas packages transitioning from optional to mandatory are usually enabled by default. In the following, to determine the names of the options, just replace the stars by the corresponding package IDs.
-^ Package ID ^ Default  ^ with_* ^ with_*_bins ^ with_*_incs ^ with_*_libs ^
-| bigdft     | Disabled | Yes    | No          | Yes         | Yes         |
-| etsf_io    | Disabled | Yes    | No          | Yes         | Yes         |
-| fox        | Disabled | Yes    | No          | Yes         | Yes         |
-| libpspio   | Disabled | Yes    | No          | Yes         | Yes         |
-| libxc      | Enabled  | Yes    | No          | Yes         | Yes         |
-| libyaml    | Disabled | Yes    | No          | Yes         | Yes         |
-| wannier90  | Disabled | Yes    | Yes         | Yes         | Yes         |
-For instance, LibXC support is enabled by default, and there are //with_libxc//, //with_libxc_incs//, and //with_libxc_libs// options, but there is no //with_libxc_bins// option.
-All these options cen be overridden by //with_extdeps_prefix//, which tells the //configure// script that all external dependencies have been installed in the same place. This option is mutually exclusive with the use of any other //with_*// option for optional features. If you decide to use it, it must be the only one.