Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Docs: Update installation instructions #2538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 16, 2024
Merged

Docs: Update installation instructions #2538

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
321 changes: 114 additions & 207 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,19 @@
# LPython

LPython is a Python compiler. It is in heavy development, currently in alpha
stage. LPython works on Windows, macOS and Linux. Some of the goals of LPython
include:

- The best possible performance for numerical, array-oriented code
- Run on all platforms
- Compile a subset of Python yet be fully compatible with Python
- Explore designs so that LPython eventually can compile all Python code
- Fast compilation
- Excellent user-friendly diagnostic messages: error, warnings, hints, notes,
etc.
- Ahead-of-Time compilation to binaries, plus interactive usage (Jupyter notebook)
- Transforming Python code to C++, Fortran and other languages

And more.
LPython is an ahead-of-time compiler for Python written in C++. It is currently in alpha
stage and under heavy development. LPython works on Windows, macOS and Linux.

Some of the goals of LPython include:

- Providing the best possible performance for numerical and array-oriented code.
- Ahead-of-Time, fast compilation to binaries, plus interactive usage (Jupyter notebook).
- Cross-platform support.
- Being able to compile a subset of Python yet be fully compatible with it.
- Transforming Python code to other programming languages like C++ and Fortran.
- Exploring design patterns so that LPython can eventually compile all Python code.
- Providing excellent user-friendly diagnostic messages: error, warnings, hints, notes, etc.

among many more.

# Sponsors

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

# Installation

## Step 0: Prerequisites

Here is the list of requirements needed to build LPython:

- Conda

For Windows, these are additionally required:

- Miniforge Prompt
- Visual Studio (with "Desktop Development with C++" workload)

Please follow the steps for your desired platform.

## Step 1: Install Conda

This step involves installing Conda using a conda-forge distribution called Miniforge.

Please follow the instructions here to install Conda on your platform:

Miniforge download link (for Linux, MacOS and Windows): https://github.com/conda-forge/miniforge/#download

## Step 2: Setting up

This step involves setting up the required configuration to run the programs in LPython.

### Linux

Run the below command to install `binutils-dev` package on Linux.

```bash
sudo apt install binutils-dev
```

### Windows

Please follow the below steps for Windows:

- Install Visual Studio, for example the version 2022.

- You can download the
Community version for free from: https://visualstudio.microsoft.com/downloads/.
- 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).

- 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:

```bash
call "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd" -arch=x64
```
Follow the steps below to install and run LPython on Linux, Windows or macOS.

- You can optionally test MSVC via:
## Prerequisites
- ### Install Conda
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.

For Windows, these are additional requirements:
- Miniforge Prompt
- Visual Studio (with "Desktop Development with C++" workload)

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

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

## Step 3: Build LPython
- Run the following command to install the build dependencies:

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

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

You may also use GitHub Desktop to do the same.
- 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:

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

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

```bash
conda env create -f environment_unix.yml
conda activate lp
```
```bash
cl /?
link /?
```

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

```bash
# if you are developing on top of a forked repository; please run following command first
# ./generate_default_tag.sh
- Windows with WSL
- Install Miniforge Prompt and add it to path:
```bash
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh -O miniconda.sh
bash miniconda.sh -b -p $HOME/conda_root
export PATH="$HOME/conda_root/bin:$PATH"
conda init bash # (shell name)
```
- Open a new terminal window and run the following commands to install dependencies:
```bash
conda create -n lp -c conda-forge llvmdev=11.0.1 bison=3.4 re2c python cmake make toml clangdev git
```

- 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/`.


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

./build0.sh
./build1.sh
```

### Windows

- Create a Conda environment using the pre-existing file:

```bash
conda env create -f environment_win.yml
conda activate lp
```

- Generate prerequisite files; build in Release Mode:

```bash
call build0.bat
call build1.bat
```

- Tests and examples

```bash
ctest
src\bin\lpython examples\expr2.py
src\bin\lpython examples\expr2.py -o a.out
a.out
```

- Whenever you are updating a test case file, you also need to update all the reference results associated with that test case:

```
python run_tests.py -u --skip-run-with-dbg
```

- To see all the options associated with LPython test suite, use:

```
python run_tests.py --help
```

## Tests:

### Linux or MacOS

- Run tests:

```bash
ctest
./run_tests.py
```

- Update test references:
```
./run_tests.py -u
```

- Run integration tests:

```bash
cd integration_tests
./run_tests.py
```
- Troubleshooting on MacOS latest version:
- In case of recently updated MacOS, you may get a warning like below in some test cases:
```bash
ld: warning: object file (test_list_index2.out.tmp.o) was built for newer macOS version (14.0) than being linked (13.3)
```
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.

```bash
git clean -dfx
sudo rm -rf /Library/Developer/CommandLineTools # make sure you know what you're doing here
sudo xcode-select --install
./build.sh
./run_tests.py
git clone https://github.com/lcompilers/lpython.git
cd lpython
```

You may also use GitHub Desktop to do the same.

## Building LPython
- ### Linux and macOS
- Create a Conda environment:

### Windows
```bash
conda env create -f environment_unix.yml
conda activate lp
```

- Run integration tests
- Generate the prerequisite files and build in Debug Mode:

```bash
python run_tests.py --skip-run-with-dbg
```
```bash
# if you are developing on top of a forked repository; please run following command first
# ./generate_default_tag.sh

- Update reference tests

```bash
python run_tests.py -u --skip-run-with-dbg
```
./build0.sh
./build1.sh
```

## Speed up Integration Tests on MacOS
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kmr-srbh some of the information seems to be removed from the previous README.md.
Can you please look into it and add them back?

Speed up Integration Tests on MacOS
Examples
Troubleshooting on MacOS latest version
Tests

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Thirumalai-Shaktivel that section was moved to the installation docs.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, then it's fine.
Yes, I can see it here: https://github.com/lcompilers/lpython/blob/main/doc/src/installation.md

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated here: #2537

- ### Windows
- Create a Conda environment using the pre-existing file:

Integration tests run slowly because Apple checks the hash of each
executable online before running.
```bash
conda env create -f environment_win.yml
conda activate lp
```

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
to run software locally that does not meet the system's security
policy."
- Generate the prerequisite files and build in Release Mode:

## Examples (Linux or MacOS)
```bash
call build0.bat
call build1.bat
```
- ### Windows with WSL

You can run the following examples manually in a terminal:
- Activate the Conda environment:
```bash
conda activate lp
```

```bash
./src/bin/lpython examples/expr2.py
./src/bin/lpython examples/expr2.py -o expr
./expr
./src/bin/lpython --show-ast examples/expr2.py
./src/bin/lpython --show-asr examples/expr2.py
./src/bin/lpython --show-cpp examples/expr2.py
./src/bin/lpython --show-llvm examples/expr2.py
./src/bin/lpython --show-c examples/expr2.py
```
- Run the following commands to build the project:
```bash
./build0.sh
cmake -DCMAKE_BUILD_TYPE=Debug -DWITH_LLVM=yes -DCMAKE_INSTALL_PREFIX=`pwd`/inst .\
make -j8
```
Check the [installation-docs](./doc/src/installation.md) for more.

## Contributing

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

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

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

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

Please report any bugs you may find at our issue tracker:
https://github.com/lcompilers/lpython/issues. Or, even better, fork the
repository on GitHub and create a PR. We welcome all changes, big or small, and
we will help you make a PR if you are new to git.
## Found a bug?
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).

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

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).

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

# Star History

Expand Down