.. sectionauthor:: Yann Pouillon Legacy building system for 4.1.5 or below. ========================================== .. note:: This is a legacy version of the build system, which is based on the arch.make file for configuration options. This method has been removed in SIESTA 5, which relies on CMake; the following how-to is only kept as reference. In this section, we describe how to compile SIESTA within a working build environment. We thus assume that you have already completed the steps explained in :doc:`requirements` and :doc:`build-prep-env`. There are 5 steps involved in the manual building of SIESTA: - Download and uncompress the source code. - Configure the build. - Compile the main executable. - Compile the utilities. - Run the test suite. We walk through them in the following subsections. Downloading the source distribution ----------------------------------- Source tarballs of SIESTA can be downloaded for most versions from the `official SIESTA releases on Gitlab`_. You can either download them from the website or through the command line. If you choose the website, the best is to use the files listed under the "Packages" section of each release. From the command line, if you want e.g. to get SIESTA 4.1.5, that would read:: wget https://gitlab.com/siesta-project/siesta/-/releases/v4.1.5/downloads/siesta-4.1.5.tar.gz Once you have the tarball on your computer, you can follow the rest of the procedure from a terminal. The next step is to uncompress the downloaded tarball, e.g.:: tar xvzf siesta-4.1.5.tar.gz cd siesta-4.1.5 Once done, you can configure the build. Configuring the build --------------------- The source tree has to be prepared before compiling SIESTA. This basically means: #. Go to the *Obj/* subdirectory or create a build directory. #. Create an *arch.make* file. #. Run the `obj_setup.sh` script. #. Check that the configuration is valid. Section "2. Compilation" of the `SIESTA User Manual`_ describes these steps for different versions of SIESTA, with specific instructions for each of them. Here we will provide a summary with examples. The first step is to use a build directory, which is a good practice because it protects the source files from being changed during the build. Unless you want to produce various SIESTA executables with different configurations from the same source tree, the recommended location is the *Obj/* subdirectory. In the case of SIESTA, this step is mandatory, since compiling from the *Src/* directory is explicitly prohibited. Creating an *arch.make* in the Obj/ subdirectory is precisely what will make the configuration of the build different from another. This file contains all the parameters we have enumerated previously in :doc:`build-prep-env` . Its structure varies between SIESTA versions, which is why we refer you to the `SIESTA Usr Manual` for details about what to tune in your *arch.make* file. If you do not know where to start from, you can use one the template provided by the *DOCUMENTED-template.make* file in *Obj/*. Before compiling SIESTA, you have to make the information about the source tree available within the build directory. This is done by running the *obj_setup.sh* script, which is found in the *Src/* subdirectory. When run from *Obj/*, the command is:: sh ../Src/obj_setup.sh .. note:: If you run it from a different build directory, the path to this script might be different. Last but not least, it is always a good idea to check that the configuration is valid by running ``make clean`` first. If this command is successful, you know that everything is ready for the build. In addition, you make sure that any artifact from a previous build is properly removed. Taking back the example of SIESTA 4.1.5 from the previous subsection, the configuration of the build would like like the following:: cd Obj cp DOCUMENTED-template.make arch.make $EDITOR arch.make sh ../Src/obj_setup.sh make clean where you replace ``$EDITOR`` by your preferred text file editor, e.g. ``emacs``, ``nano`` or ``vim``. Compiling SIESTA ---------------- The slow and robust solution to compile SIESTA is to type ``make``. If you have configured the build correctly, this will work with any version of SIESTA. After a few minutes, you should find a ``siesta`` executable in the build directory. However, if you have SIESTA 4.1 or a more recent version, you can also compile the source code faster, through ``make -j N``, where ``N`` is the maximum number of files to compile at the same time. A good number is anything between 2 and the number of cores of your CPU. If in doubt, try ``make -j 4``, which works in almost any recent computer. .. note:: If you get an error when compiling with ``make -j N``, run ``make`` again without arguments to find out where the error occurred. Once done, you can check that the SIESTA executable has actually been generated by typing ``ls -ltr``. The last file in the list should be named *siesta*. Compiling the SIESTA utilities ------------------------------ In the build directory, after configuring the build, you will find a subdirectory named *Util/*. If you go there, you will be able to build various pre- and post-processing tools that might help you with your SIESTA calculations. To see the full list, type:: cd Util ls For more details about these utilities, you can consult the README file there. If you want to build them all, you can use the *build_all.sh* script:: ./build_all.sh However, since it can take some time, and since you might not need all of them, you can also build a few utilities one by one. For instance, if you want to build the *gnubands* utility to plot band structures with Gnuplot, you would type:: cd Bands make clean make ls -ltr After that, if you want to build *denchar*, you would type:: cd ../Denchar/Src make clean make ls -ltr You're now done with building executables. .. _`SIESTA User Manual`: https://siesta-project.org/SIESTA_MATERIAL/Docs/Manuals/manuals.html .. _`official SIESTA releases on Gitlab`: https://gitlab.com/siesta-project/siesta/-/releases