Skip to content

Commit 094f1ca

Browse files
briantobybriantoby
committed
add meson to compile info; needs more work for Windows
1 parent 2dbaaae commit 094f1ca

File tree

1 file changed

+136
-6
lines changed

1 file changed

+136
-6
lines changed

‎webdocs/compile.rst‎

Lines changed: 136 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,41 @@
1313
Compiling GSAS-II
1414
======================
1515

16-
A small amount of GSAS-II code is written in Fortran and one routine in C, rather than Python, to provide improved computation speed. Other large and complex capabilities, such as the GSAS(-I) space group interpretation code and DIFFaX are also used as as Fortran code. This code must be compiled before it is run. Normally this is done for you, but on occasion it must be done locally.
16+
The vast majority of GSAS-II's code is written in Python, but where
17+
speed or complex analysis is
18+
needed a small amount of code is written in other languages. There are
19+
several small routines in Fortran used for speed, as well as the
20+
complex codes for space group
21+
analysis code (taken from the original GSAS package) and the DIFFaX
22+
code, for faulted materials, has also been incorporated.
23+
There is also one routine
24+
for image analysis written in C and one for magnetic k-vector
25+
analysis, written in Cython. There are also two small stand-alone
26+
programs used for the NIST*LATTICE unit cell analysis capability.
27+
All of these routines must be compiled to provide dynamic-link
28+
libraries and executable programs, which we refer to collectively as the GSAS-II
29+
binaries. Versions of these must match the operating system where they
30+
will be run and must also match the version of Python and numpy module
31+
that they will be used with. Most users will install versions of the GSAS-II
32+
binaries that have been distributed with GSAS-II, but they can be
33+
compiled by users and in some cases that will be necessary. The
34+
documentation here discusses these files.
35+
36+
Note that there are two methods used for compiling GSAS-II. For Python
37+
3.11 and earlier, a build process with a utility called `Scons` was used, but this
38+
stopped working for GSAS-II with Python 3.12 and a new build process
39+
using the `meson` tool was implemented. At present, there are two
40+
branches for GSAS-II. The `master` branch uses Scons and the
41+
`main` branch uses meson. The master branch is the current default
42+
branch but will eventually be retired in favor of the newer `main`
43+
branch.
44+
45+
Supplied Binary Files
46+
---------------------------
47+
48+
The GSAS-II binaries are supplied on GitHub as "release" files,
49+
https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/latest. In
50+
that location, the files are in tar archives named `prefix_pX.X_nY.Y.tgz`
1751

1852
The supplied binaries are placed in a subdirectory name with name
1953
`prefix`\ _p\ `X.X`\ _n\ `Y.Y` where
@@ -26,11 +60,109 @@ The supplied binaries are placed in a subdirectory name with name
2660
* Linux: ARM processors (64-bit and 32-bit Raspberry Pi OS only).
2761
[Prefixes `linux_arm32_` and `linux_arm64_`\ ]
2862

29-
Some older versions combinations of Python and
30-
NumPy can be found in the older svn repository for GSAS-II:
63+
Some older binary files with combinations of older Python and
64+
NumPy versions can be found in the older svn repository for GSAS-II:
3165
https://subversion.xray.aps.anl.gov/trac/pyGSAS/browser/Binaries
3266

33-
The compilation process requires installation of the gcc and gfortran compilers. Others may be possible, but have not been tried. Also, the Python Scons package must be installed into Python. compilation is done with commands::
67+
Compiling with meson
68+
---------------------------
69+
70+
Compiling GSAS-II binaries is quite simple. One needs to install the
71+
Python meson and cython packages and a C compiler and the Gfortran
72+
compiler. On Linux it probably best to use compilers supplied with the
73+
dist using a commands such as `apt-get` or `yum`,
74+
but these compilers can be installed via conda
75+
from conda-forge and the latter does not require admin privs.
76+
On windows and MacOS, the easist way to obtain them
77+
is via their conda packages.
78+
79+
Windows::
80+
81+
conda install meson cython gcc gfortran -c conda-forge
82+
83+
MacOS::
84+
85+
conda install meson cython clang compilers -c conda-forge
86+
87+
Linux::
88+
89+
sudo apt-get gcc gfortran # or use the yum command
90+
yum install gcc-gfortran
91+
conda install meson cython -c conda-forge
92+
93+
Once meson and the tools are installed, the following steps are needed
94+
to build the GSAS-II binaries.
95+
96+
1. Download the GSAS-II sources (if not already done) and move to the directory::
97+
98+
cd <...> # select where you wish to install GSAS-II
99+
git clone [email protected]:AdvancedPhotonSource/GSAS-II.git --depth 1 -b main G2
100+
cd G2
101+
102+
2. Create a scratch directory to compile GSAS-II into::
103+
104+
meson setup /tmp/GSASIIc
105+
106+
Note that this command will fail if cython, gfortran and a c
107+
complier is not found. If the flang compiler is found, meson will
108+
use it, but the resulting binaries will not work properly.
109+
110+
3. Move to the setup directory and compile::
111+
112+
cd /tmp/GSASIIc
113+
meson compile
114+
115+
4. (A) Install the GSAS-II binaries so they can be used by the current user::
116+
117+
meson compile local-install
118+
119+
This command will copy the compiled files to `~/.GSASII/bin`, which
120+
is appropriate for when one user will access the GSAS-II
121+
program. It also allows multiple GSAS-II installations (should a
122+
user wish to keep multiple versions available).
123+
124+
4. (B) Or when GSAS-II is installed on a server, the GSAS-II binaries
125+
can be placed with the GSAS-II source files installed with the git
126+
command (into .../G2)::
127+
128+
meson compile system-install
129+
130+
If the first command used was `cd ~/software` then GSAS-II was
131+
installed into `~/software/G2` and the binaries will be installed into
132+
`~/software/G2/GSASII/bin`.
133+
134+
5. Clean up:
135+
136+
rm -rf /tmp/GSASIIc
137+
138+
6. (Optional) Create shortcuts:
139+
140+
Windows::
141+
142+
python .../G2/GSASII/install/makeBat.py
143+
144+
Linux::
145+
146+
python .../G2/GSASII/install/makeLinux.py
147+
148+
MacOS::
149+
150+
python .../G2/GSASII/install/makeMacApp.py
151+
152+
153+
Compiling with Scons
154+
---------------------------
155+
156+
Compilation with scons (as opposed to meson, as discussed above) is not
157+
recommended and will be removed from GSAS-II in the future. It will
158+
work only with Python 3.11 or older and only with the `master`
159+
branch. GSAS-II will fail with Python earlier than 3.7 and may have
160+
some errors even with Python 3.8.
161+
162+
The compilation process requires installation of the gcc and gfortran
163+
compilers. Others will probablu not work. Also, the Python Scons
164+
package must be installed into Python. compilation is done with
165+
commands::
34166

35167
cd fsource
36168
scons
@@ -49,5 +181,3 @@ Note that the intent is that this Scons-based process will be replaced with one
49181
* https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/CompilingWindows
50182
* https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/InstallMacHardWay#CompilingFortranCode
51183
* https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/InstallLinux#CompilingFortranCode
52-
53-

0 commit comments

Comments
 (0)