Skip to content

Commit a750efb

Browse files
certikcertik
authored
Merge pull request #2538 from kmr-srbh/docs
Update installation instructions
2 parents 49f7b73 + 1cdc4cb commit a750efb

File tree

1 file changed

+114
-207
lines changed

1 file changed

+114
-207
lines changed

‎README.md‎

Lines changed: 114 additions & 207 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,19 @@
11
# LPython
22

3-
LPython is a Python compiler. It is in heavy development, currently in alpha
4-
stage. LPython works on Windows, macOS and Linux. Some of the goals of LPython
5-
include:
6-
7-
- The best possible performance for numerical, array-oriented code
8-
- Run on all platforms
9-
- Compile a subset of Python yet be fully compatible with Python
10-
- Explore designs so that LPython eventually can compile all Python code
11-
- Fast compilation
12-
- Excellent user-friendly diagnostic messages: error, warnings, hints, notes,
13-
etc.
14-
- Ahead-of-Time compilation to binaries, plus interactive usage (Jupyter notebook)
15-
- Transforming Python code to C++, Fortran and other languages
16-
17-
And more.
3+
LPython is an ahead-of-time compiler for Python written in C++. It is currently in alpha
4+
stage and under heavy development. LPython works on Windows, macOS and Linux.
5+
6+
Some of the goals of LPython include:
7+
8+
- Providing the best possible performance for numerical and array-oriented code.
9+
- Ahead-of-Time, fast compilation to binaries, plus interactive usage (Jupyter notebook).
10+
- Cross-platform support.
11+
- Being able to compile a subset of Python yet be fully compatible with it.
12+
- Transforming Python code to other programming languages like C++ and Fortran.
13+
- Exploring design patterns so that LPython can eventually compile all Python code.
14+
- Providing excellent user-friendly diagnostic messages: error, warnings, hints, notes, etc.
15+
16+
among many more.
1817

1918
# Sponsors
2019

@@ -25,235 +24,143 @@ LFortran, see that project for a list of sponsors.
2524

2625
# Installation
2726

28-
## Step 0: Prerequisites
29-
30-
Here is the list of requirements needed to build LPython:
31-
32-
- Conda
33-
34-
For Windows, these are additionally required:
35-
36-
- Miniforge Prompt
37-
- Visual Studio (with "Desktop Development with C++" workload)
38-
39-
Please follow the steps for your desired platform.
40-
41-
## Step 1: Install Conda
42-
43-
This step involves installing Conda using a conda-forge distribution called Miniforge.
44-
45-
Please follow the instructions here to install Conda on your platform:
46-
47-
Miniforge download link (for Linux, MacOS and Windows): https://github.com/conda-forge/miniforge/#download
48-
49-
## Step 2: Setting up
50-
51-
This step involves setting up the required configuration to run the programs in LPython.
52-
53-
### Linux
54-
55-
Run the below command to install `binutils-dev` package on Linux.
56-
57-
```bash
58-
sudo apt install binutils-dev
59-
```
60-
61-
### Windows
62-
63-
Please follow the below steps for Windows:
64-
65-
- Install Visual Studio, for example the version 2022.
66-
67-
- You can download the
68-
Community version for free from: https://visualstudio.microsoft.com/downloads/.
69-
- After installing Visual Studio and running the Visual Studio Installer, you must install the "Desktop Development with C++" workload which will install Visual C++ Compiler (MSVC).
70-
71-
- Launch the Miniforge prompt from the Desktop.
72-
73-
- It is recommended to use MiniForge instead of Powershell as the main terminal to build and write code for LPython.
74-
75-
- In the MiniForge Prompt, initialize the MSVC compiler using the below command:
76-
77-
```bash
78-
call "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd" -arch=x64
79-
```
27+
Follow the steps below to install and run LPython on Linux, Windows or macOS.
8028

81-
- You can optionally test MSVC via:
29+
## Prerequisites
30+
- ### Install Conda
31+
Follow the instructions provided [here](https://github.com/conda-forge/miniforge/#download) to install Conda on your platform (Linux, macOS and Windows) using a conda-forge distribution called Miniforge.
32+
33+
For Windows, these are additional requirements:
34+
- Miniforge Prompt
35+
- Visual Studio (with "Desktop Development with C++" workload)
8236

83-
```bash
84-
cl /?
85-
link /?
86-
```
37+
- ### Set up your system
38+
- Linux
39+
- Make sure you have `g++` and `cmake` installed. If not, install them using the below command:
8740

88-
Both commands must print several pages of help text.
41+
```bash
42+
sudo apt-get install g++ cmake
43+
```
8944

90-
## Step 3: Build LPython
45+
- Run the following command to install the build dependencies:
9146

92-
- Clone LPython using the following commands
47+
```bash
48+
sudo apt-get install binutils-dev build-essential zlib1g-dev bison re2c flex
49+
```
50+
- Windows
51+
- Download and install [Microsoft Visual Studio Community](https://visualstudio.microsoft.com/downloads/) for free.
9352

94-
```bash
95-
git clone https://github.com/lcompilers/lpython.git
96-
cd lpython
97-
```
53+
- Run the Visual Studio Installer. Download and install the "Desktop Development with C++" workload which will install the Visual C++ Compiler (MSVC).
9854

99-
You may also use GitHub Desktop to do the same.
55+
- Launch the Miniforge prompt from the Desktop. It is recommended to use MiniForge instead of Powershell as the main terminal to build and write code for LPython. In the MiniForge Prompt, initialize the MSVC compiler using the below command:
10056

101-
### Linux and MacOS
57+
```bash
58+
call "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd" -arch=x64
59+
```
10260

103-
- Create a Conda environment using the pre-existing file:
61+
You can optionally test MSVC via:
10462

105-
```bash
106-
conda env create -f environment_unix.yml
107-
conda activate lp
108-
```
63+
```bash
64+
cl /?
65+
link /?
66+
```
10967

110-
- Generate prerequisite files; build in Debug Mode:
68+
Both commands must print several pages of help text.
11169

112-
```bash
113-
# if you are developing on top of a forked repository; please run following command first
114-
# ./generate_default_tag.sh
70+
- Windows with WSL
71+
- Install Miniforge Prompt and add it to path:
72+
```bash
73+
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O miniconda.sh
74+
bash miniconda.sh -b -p $HOME/conda_root
75+
export PATH="$HOME/conda_root/bin:$PATH"
76+
conda init bash # (shell name)
77+
```
78+
- Open a new terminal window and run the following commands to install dependencies:
79+
```bash
80+
conda create -n lp -c conda-forge llvmdev=11.0.1 bison=3.4 re2c python cmake make toml clangdev git
81+
```
82+
83+
- Optionally, you can change the directory to a Windows location using `cd /mnt/[drive letter]/[windows location]`. For e.g. - `cd mnt/c/Users/name/source/repos/`.
11584

85+
86+
- ### Clone the LPython repository
87+
Make sure you have `git` installed. Type the following command to clone the repository:
11688

117-
./build0.sh
118-
./build1.sh
119-
```
120-
121-
### Windows
122-
123-
- Create a Conda environment using the pre-existing file:
124-
125-
```bash
126-
conda env create -f environment_win.yml
127-
conda activate lp
128-
```
129-
130-
- Generate prerequisite files; build in Release Mode:
131-
132-
```bash
133-
call build0.bat
134-
call build1.bat
135-
```
136-
137-
- Tests and examples
138-
139-
```bash
140-
ctest
141-
src\bin\lpython examples\expr2.py
142-
src\bin\lpython examples\expr2.py -o a.out
143-
a.out
144-
```
145-
146-
- Whenever you are updating a test case file, you also need to update all the reference results associated with that test case:
147-
148-
```
149-
python run_tests.py -u --skip-run-with-dbg
150-
```
151-
152-
- To see all the options associated with LPython test suite, use:
153-
154-
```
155-
python run_tests.py --help
156-
```
157-
158-
## Tests:
159-
160-
### Linux or MacOS
161-
162-
- Run tests:
163-
164-
```bash
165-
ctest
166-
./run_tests.py
167-
```
168-
169-
- Update test references:
170-
```
171-
./run_tests.py -u
172-
```
173-
174-
- Run integration tests:
175-
176-
```bash
177-
cd integration_tests
178-
./run_tests.py
179-
```
180-
- Troubleshooting on MacOS latest version:
181-
- In case of recently updated MacOS, you may get a warning like below in some test cases:
18289
```bash
183-
ld: warning: object file (test_list_index2.out.tmp.o) was built for newer macOS version (14.0) than being linked (13.3)
184-
```
185-
This leads to mismatch of hashes with expected output in some test cases, this can be resolved by updating command line tools. Below is a snippet for the same.
186-
187-
```bash
188-
git clean -dfx
189-
sudo rm -rf /Library/Developer/CommandLineTools # make sure you know what you're doing here
190-
sudo xcode-select --install
191-
./build.sh
192-
./run_tests.py
90+
git clone https://github.com/lcompilers/lpython.git
91+
cd lpython
19392
```
93+
94+
You may also use GitHub Desktop to do the same.
19495

96+
## Building LPython
97+
- ### Linux and macOS
98+
- Create a Conda environment:
19599

196-
### Windows
100+
```bash
101+
conda env create -f environment_unix.yml
102+
conda activate lp
103+
```
197104

198-
- Run integration tests
105+
- Generate the prerequisite files and build in Debug Mode:
199106

200-
```bash
201-
python run_tests.py --skip-run-with-dbg
202-
```
107+
```bash
108+
# if you are developing on top of a forked repository; please run following command first
109+
# ./generate_default_tag.sh
203110
204-
- Update reference tests
205111
206-
```bash
207-
python run_tests.py -u --skip-run-with-dbg
208-
```
112+
./build0.sh
113+
./build1.sh
114+
```
209115

210-
## Speed up Integration Tests on MacOS
116+
- ### Windows
117+
- Create a Conda environment using the pre-existing file:
211118

212-
Integration tests run slowly because Apple checks the hash of each
213-
executable online before running.
119+
```bash
120+
conda env create -f environment_win.yml
121+
conda activate lp
122+
```
214123

215-
You can turn off that feature in the Privacy tab of the Security and Privacy item of System Preferences > Developer Tools > Terminal.app > "allow the apps below
216-
to run software locally that does not meet the system's security
217-
policy."
124+
- Generate the prerequisite files and build in Release Mode:
218125

219-
## Examples (Linux or MacOS)
126+
```bash
127+
call build0.bat
128+
call build1.bat
129+
```
130+
- ### Windows with WSL
220131

221-
You can run the following examples manually in a terminal:
132+
- Activate the Conda environment:
133+
```bash
134+
conda activate lp
135+
```
222136

223-
```bash
224-
./src/bin/lpython examples/expr2.py
225-
./src/bin/lpython examples/expr2.py -o expr
226-
./expr
227-
./src/bin/lpython --show-ast examples/expr2.py
228-
./src/bin/lpython --show-asr examples/expr2.py
229-
./src/bin/lpython --show-cpp examples/expr2.py
230-
./src/bin/lpython --show-llvm examples/expr2.py
231-
./src/bin/lpython --show-c examples/expr2.py
232-
```
137+
- Run the following commands to build the project:
138+
```bash
139+
./build0.sh
140+
cmake -DCMAKE_BUILD_TYPE=Debug -DWITH_LLVM=yes -DCMAKE_INSTALL_PREFIX=`pwd`/inst .\
141+
make -j8
142+
```
143+
Check the [installation-docs](./doc/src/installation.md) for more.
233144

234145
## Contributing
235146

236-
We welcome contributions from anyone, even if you are new to compilers or to
237-
open source. It might sound daunting to contribute to a compiler at first, but
238-
please do, it is not complicated. We will help you with technical issues and
239-
help improve your contribution so that it can be merged.
147+
We welcome contributions from anyone, even if you are new to compilers or open source in general.
148+
It might sound daunting at first to contribute to a compiler, but do not worry, it is not that complicated.
149+
We will help you with any technical issues you face and provide support so your contribution gets merged.
240150

241-
To contribute, submit a Pull Request (PR) against our repository at:
151+
To contribute, submit a Pull Request (PR) against our repository at: https://github.com/lcompilers/lpython
242152

243-
https://github.com/lcompilers/lpython
153+
Do not forget to clean your history, see [example](./doc/src/rebasing.md).
244154

245-
and don't forget to clean your history, see [example](./doc/src/rebasing.md).
155+
See the [CONTRIBUTING](CONTRIBUTING.md) document for more information.
246156

247-
Please report any bugs you may find at our issue tracker:
248-
https://github.com/lcompilers/lpython/issues. Or, even better, fork the
249-
repository on GitHub and create a PR. We welcome all changes, big or small, and
250-
we will help you make a PR if you are new to git.
157+
## Found a bug?
158+
Please report any bugs you find at our issue tracker [here](https://github.com/lcompilers/lpython/issues). Or, even better, fork the repository on GitHub and create a Pull Request (PR).
251159

252-
If you have any questions or need help, please ask us at Zulip ([![project
253-
chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://lfortran.zulipchat.com/))
254-
or our [mailinglist](https://groups.io/g/lfortran).
160+
We welcome all changes, big or small. We will help you make a PR if you are new to git.
161+
162+
If you have any questions or need help, please ask us at [Zulip](https://lfortran.zulipchat.com/) or on our [mailinglist](https://groups.io/g/lfortran).
255163

256-
See the [CONTRIBUTING](CONTRIBUTING.md) document for more information.
257164

258165
# Star History
259166

0 commit comments

Comments
 (0)