Installation
All the instructions below work on Linux, macOS and Windows.
Binaries
The recommended way to install LFortran is using Conda.
Install Conda for example by installing the
Miniconda installation by following instructions there for your platform.
Then create a new environment (you can choose any name, here we chose lf
) and
activate it:
lf
environment has the lfortran
compiler available, you can start the
interactive prompt by executing lfortran
, or see the command line options using
lfortran -h
.
The Jupyter kernel is automatically installed by the above command, so after installing Jupyter itself:
You can create a Fortran based Jupyter notebook by executing: and selectingNew->Fortran
.
Build From a Source Tarball
This method is the recommended method if you just want to install LFortran, either yourself or in a package manager (Spack, Conda, Debian, etc.). The source tarball has all the generated files included and has minimal dependencies.
First we have to install dependencies, for example using Conda:
Then download a tarball from https://lfortran.org/download/, e.g.:wget https://lfortran.github.io/tarballs/dev/lfortran-0.9.0.tar.gz
tar xzf lfortran-0.9.0.tar.gz
cd lfortran-0.9.0
lfortran
into the inst/bin
.
Build From Git
We assume you have C++ compilers installed, as well as git
and wget
.
In Ubuntu, you can also install binutils-dev
for stacktraces.
If you do not have Conda installed, you can do so on Linux (and similarly on other platforms):
wget --no-check-certificate https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
bash miniconda.sh -b -p $HOME/conda_root
export PATH="$HOME/conda_root/bin:$PATH"
conda create -n lf -c conda-forge llvmdev=11.0.1 bison=3.4 re2c python cmake make toml
conda activate lf
re2c
, bison
and python
):
Now the process is the same as installing from the source tarball. For example to build in Debug mode:
Run tests:
Run an interactive prompt:Build from Git on Windows with Visual Studio
Install Visual Studio (MSVC), for example the version 2022, you can download the Community version for free from: https://visualstudio.microsoft.com/downloads/.
Install miniforge using the Windows installer from https://github.com/conda-forge/miniforge.
Launch the Miniforge Prompt from the Desktop.
In the shell, initialize the MSVC compiler using:
You can optionally test that MSVC works by:
Both commands must print help (several pages).Now you can download and build LFortran:
git clone https://github.com/lfortran/lfortran.git
cd lfortran
conda env create -f environment_win.yml
conda activate lf
build0.bat
build1.bat
If everything compiled, then you can use LFortran as follows:
And so on.Note: LFortran currently uses the MSVC's linker program (link
), which is only
available when the MSVC bat script above is ran. If you forget to activate it,
LFortran's linking will fail.
Note: the miniforge shell seems to be running some version of git-bash
(although it is cmd.exe
), which has some unix-like filesystem mounted in
/usr
and several commands available such as ls
, which
, git
, vim
. For
this reason the Conda build environment_win.yml
contains everything needed,
including git
.
Build from Git on Windows with WSL
- In windows search "turn windows features on or off".
- Tick Windows subsystem for Linux.
- Press OK and restart computer.
- Go to Microsoft store and download Ubuntu 20.04, and launch it.
- Run the following commands.
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 create -n lf -c conda-forge llvmdev=11.0.1 bison=3.4 re2c python cmake make toml
conda init bash
conda activate lf
sudo apt update
sudo apt-get install build-essential
sudo apt-get install zlib1g-dev
sudo apt install clang
cd /mnt/[drive letter]/[windows location]
.
* e.g. cd mnt/c/Users/name/source/repos/
-
Now clone the LFortran git repository
-
Run the following commands
-
If everything compiles, you can use LFortran as follows
-
Run an interactive prompt
-
Run tests
Enabling the Jupyter Kernel
To install the Jupyter kernel, install the following Conda packages also:
and enable the kernel by-DWITH_XEUS=yes
and install into $CONDA_PREFIX
. For
example:
cmake \
-DCMAKE_BUILD_TYPE=Debug \
-DWITH_LLVM=yes \
-DWITH_XEUS=yes \
-DCMAKE_PREFIX_PATH="$CONDA_PREFIX" \
-DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX" \
.
cmake --build . -j4 --target install
conda install jupyter
) and test that the LFortran
kernel was found:
Then launch a Jupyter notebook as follows:
Click New->Fortran
. To launch a terminal jupyter LFortran console:
Build From Git with Nix
One of the ways to ensure exact environment and dependencies is with nix
. This will ensure that system dependencies do not interfere with the development environment. If you want, you can report bugs in a nix-shell
environment to make it easier for others to reproduce.
With Root
We start by getting nix
. The following multi-user installation will work on any machine with a Linux distribution, MacOS or Windows (via WSL):
Without Root
If you would like to not provide nix
with root access to your machine, on Linux distributions we can use nix-portable.
nix-shell
commands with NP_RUNTIME=bwrap ./nix-portable
. So:
Development
Now we can enter the development environment:
The--pure
flag ensures no system dependencies are used in the environment.
The build steps are the same as with the ci
:
To change the compilation environment from gcc
(default) to clang
we can use --argstr
:
Note About Dependencies
End users (and distributions) are encouraged to use the tarball from https://lfortran.org/download/, which only depends on LLVM, CMake and a C++ compiler.
The tarball is generated automatically by our CI (continuous integration) and contains some autogenerated files: the parser, the AST and ASR nodes, which is generated by an ASDL translator (requires Python).
The instructions from git are to be used when developing LFortran itself.
Note for users who do not use Conda
Following are the dependencies necessary for installing this repository in development mode,
- Bison - 3.5.1
- LLVM - 11.0.1
- re2c - 2.0.3
- binutils - 2.31.90 - Make sure that you should enable the required options related to this dependency to build the dynamic libraries (the ones ending with
.so
).
Stacktraces
LFortran can print stacktraces when there is an unhandled exception, as well as
on any compiler error with the --show-stacktrace
option. This is very helpful
for developing the compiler itself to see where in LFortran the problem is. The
stacktrace support is turned off by default, to enable it,
compile LFortran with the -DWITH_STACKTRACE=yes
cmake option after installing
the prerequisites on each platform per the instructions below.
Ubuntu
In Ubuntu, apt install binutils-dev
.
macOS
If you use the default Clang compiler on macOS, then the stacktraces should
just work on both Intel and M1 based macOS (the CMake build system
automatically invokes the dsymtuil
tool and our Python scripts to store the
debug information, see src/bin/CMakeLists.txt
for more details). If it does
not work, please report a bug.
If you do not like the default way, an alternative is to use bintutils. For that, first install Spack, then:
The last command will show a full path to the installedbinutils
package. Add
this path to your shell config file, e.g.:
export CMAKE_PREFIX_PATH_LFORTRAN=/Users/ondrej/repos/spack/opt/spack/darwin-catalina-broadwell/apple-clang-11.0.0/binutils-2.36.1-wy6osfm6bp2323g3jpv2sjuttthwx3gd
-DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH_LFORTRAN;$CONDA_PREFIX"
cmake option.
The $CONDA_PREFIX
is there if you install some other dependencies (such as
llvm
) using Conda, otherwise you can remove it.