Skip to content

Commit 9c5cef9

Browse files
author
Ritvik Rao
committed
docs change to emphasize current way to build charm4py for python 3.8 and later
1 parent b0ecc20 commit 9c5cef9

File tree

1 file changed

+49
-46
lines changed

1 file changed

+49
-46
lines changed

docs/install.rst

Lines changed: 49 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -15,53 +15,57 @@ CPython (most common implementation) and PyPy_.
1515
.. _PyPy: http://pypy.org
1616

1717

18-
pip
19-
---
20-
21-
To install on regular Linux, macOS and Windows machines, do::
18+
Manually building the Charm++ shared library (required for Python 3.8 and newer)
19+
--------------------------------------------
2220

23-
$ pip3 install charm4py
21+
This is needed when building Charm++ for specialized machine/network layers
22+
other than TCP and MPI (e.g. Cray XC/XE). It is also currently needed for Python versions
23+
3.8 and newer, since the current pip package of Charm4py is only compatible with Python 3.7
24+
and older.
2425

25-
.. note::
26+
Before installing, you need the following prerequisites:
27+
- CPython: numpy, greenlet and cython (``pip3 install 'numpy>=1.10.0' cython greenlet``)
28+
- PyPy: none
2629

27-
This option uses Charm++'s TCP layer as the communication layer.
28-
If you want a faster communication layer (e.g. MPI), see "Install from
29-
source" below.
30+
The first step is to clone the Charm4py repository from Git::
3031

31-
pip >= 8.0 is recommended to simplify the install and avoid building Charm4py or
32-
any dependencies from sources.
32+
$ git clone https://github.com/UIUC-PPL/charm4py
33+
$ cd charm4py
3334

34-
Note that a 64-bit version of Python is required to install and run Charm4py.
35+
Next, create a folder called charm_src in the charm4py repo, and then clone the Charm++ repo
36+
into that folder::
3537

38+
$ mkdir charm_src && cd charm_src
39+
$ git clone https://github.com/UIUC-PPL/charm
3640

37-
Install from source
38-
-------------------
41+
Once this is done, there are two ways to build Charm4py. The first way is to change back up
42+
into the Charm4Py directory and run the install script::
43+
44+
$ cd ..
45+
$ python3 setup.py install [--mpi]
3946

40-
.. note::
41-
This is not required if installing from a binary wheel with pip.
47+
The optional flag ``--mpi``, when enabled, will build the
48+
Charm++ library with the MPI communication layer (MPI headers and libraries
49+
need to be installed on the system). After this, Charm4Py will be built.
4250

43-
Prerequisites:
44-
- CPython: numpy, greenlet and cython (``pip3 install 'numpy>=1.10.0' cython greenlet``)
45-
- PyPy: none
51+
The other option is to manually build Charm++ before building Charm4py. To do this, change to
52+
the charm directory and run the following build command::
53+
54+
$ cd charm
55+
$ ./build charm4py <version> -j<N> --with-production
4656

47-
To build the latest *stable* release, do::
57+
Then, return to the charm4py directory and run setup.py::
4858

49-
$ pip3 install [--install-option="--mpi"] charm4py --no-binary charm4py
59+
$ cd ../..
60+
$ python3 setup.py install [--mpi]
5061

51-
Or download the source distribution from PyPI, uncompress and run
52-
``python3 setup.py install [--mpi]``.
5362

54-
The optional flag ``--mpi``, when enabled, will build the
55-
Charm++ library with the MPI communication layer (MPI headers and libraries
56-
need to be installed on the system).
63+
After building, you can run Charm4py examples. One example you can try is
64+
array_hello.py, which can be run as follows::
5765

58-
To build the latest *development* version, download Charm4py and Charm++ source code
59-
and run setup::
66+
$ cd examples/hello
67+
$ python -m charmrun.start +p2 array_hello.py
6068

61-
$ git clone https://github.com/UIUC-PPL/charm4py
62-
$ cd charm4py
63-
$ git clone https://github.com/UIUC-PPL/charm charm_src/charm
64-
$ python3 setup.py install [--mpi]
6569

6670
.. note::
6771

@@ -72,25 +76,24 @@ and run setup::
7276
to manually build the Charm++ library (see below).
7377

7478

75-
Manually building the Charm++ shared library
76-
--------------------------------------------
79+
pip (Python 3.7 and older)
80+
---
7781

78-
This is needed when building Charm++ for specialized machine/network layers
79-
other than TCP and MPI (e.g. Cray XC/XE).
82+
To install on regular Linux, macOS and Windows machines, do::
8083

81-
Before running ``python3 setup.py`` in the steps above, enter the Charm++ source code
82-
directory (``charm_src/charm``), and manually build the Charm++ library. The build
83-
command syntax is::
84+
$ pip3 install charm4py
8485

85-
$ ./build charm4py <version> -j<N> --with-production
86+
.. note::
8687

87-
where ``<version>`` varies based on the system and communication layer, and ``<N>``
88-
is the number of processes to use for compiling.
89-
For help in choosing the correct ``<version>``, please refer to the Charm++ manual_
90-
and the README in Charm++'s root directory.
88+
This option uses Charm++'s TCP layer as the communication layer.
89+
If you want a faster communication layer (e.g. MPI), see "Install from
90+
source" below.
91+
92+
pip >= 8.0 is recommended to simplify the install and avoid building Charm4py or
93+
any dependencies from sources.
94+
95+
Note that a 64-bit version of Python is required to install and run Charm4py.
9196

92-
After the library has been built, continue with ``python3 setup.py install`` in the
93-
Charm4py source root directory.
9497

9598

9699
.. _manual: https://charm.readthedocs.io/en/latest/charm++/manual.html#installing-charm

0 commit comments

Comments
 (0)