Installing Solang
=================
The Solang compiler is a single binary. It can be installed in different ways, listed below.
1. :ref:`Download from Homebrew <download-brew>` (MacOS only)
2. :ref:`Download binaries <download-binaries>`
3. :ref:`Download from a Docker container <download-docker>`
4. :ref:`Build using Dockerfile <build-dockerfile>`
5. :ref:`Build from source <build-source>`
Option 1: Download from Brew
----------------------------
Solang is available on Brew via a private tap. This works only for MacOS systems, both Intel and Apple Silicon.
To install Solang via Brew, run the following command:
.. code-block:: text
brew install hyperledger/solang/solang
Option 2: Download binaries
---------------------------
There are binaries available on github releases:
- `Linux x86-64 <https://github.com/hyperledger/solang/releases/download/v0.2.1/solang-linux-x86-64>`_
- `Linux arm64 <https://github.com/hyperledger/solang/releases/download/v0.2.1/solang-linux-arm64>`_
- `Windows x64 <https://github.com/hyperledger/solang/releases/download/v0.2.1/solang.exe>`_
- `MacOS intel <https://github.com/hyperledger/solang/releases/download/v0.2.1/solang-mac-intel>`_
- `MacOS arm <https://github.com/hyperledger/solang/releases/download/v0.2.1/solang-mac-arm>`_
Download the file and save it somewhere in your ``$PATH``, for example the bin directory in your home directory. If the
path you use is not already in ``$PATH``, then you need to add it yourself.
On MacOS, remember to give execution permission to the file and remove it from quarantine by executing the following commands:
.. code-block:: bash
chmod +x solang-mac-arm
xattr -d com.apple.quarantine solang-mac-arm
If you are using an Intel based Mac, please, exchange ``solang-mac-arm`` by ``solang-mac-intel`` in both of the above commands.
On Linux, permission to execute the binary is also necessary, so, please, run ``chmod +x solang-linux-x86-64``. If you
are using an Arm based Linux, the command is the following: ``chmod +x solang-linux-arm64``.
Option 3: Use ghcr.io/hyperledger/solang containers
---------------------------------------------------
New images are automatically made available on
`solang containers <https://github.com/hyperledger/solang/pkgs/container/solang>`_.
There is a release `v0.2.1` tag and a `latest` tag:
.. code-block:: bash
docker pull ghcr.io/hyperledger/solang:latest
The Solang binary is stored at ``/usr/bin/solang`` in this image. The `latest` tag
gets updated each time there is a commit to the main branch of the Solang git repository.
Option 4: Build Solang using Dockerfile
---------------------------------------
First clone the git repo using:
.. code-block:: bash
git clone https://github.com/hyperledger/solang
Then you can build the image using:
.. code-block:: bash
docker image build .
Option 5: Build Solang from source
----------------------------------
In order to build Solang from source, you will need rust 1.63.0 or higher,
and a build of LLVM based on the Solana LLVM tree. There are a few LLVM patches required that are not upstream yet.
First, follow the steps below for installing LLVM and then proceed from there.
If you do not have the correct version of rust installed, go to `rustup <https://rustup.rs/>`_.
To install Solang from sources, do the following:
1. :ref:`Install LLVM <install-llvm>` from Solana's LLVM fork.
2. :ref:`Build Solang <build-from-source>` from its source files.
Solang is also available on `crates.io`, so after completing step #1 from above, it is possible to :ref:`build it using the
release <build-from-crates>` on crates.
Step 1: Install the LLVM Libraries
_____________________________________
Solang needs a build of
`LLVM with some extra patches <https://github.com/solana-labs/llvm-project/>`_.
These patches make it possible to generate code for Solana, and fixes
concurrency issues in the lld linker.
You can either download the pre-built libraries from
`github <https://github.com/hyperledger/solang/releases/tag/v0.2.1>`_
or :ref:`build your own from source <llvm-from-source>`. After that, you need to add the ``bin`` of your
LLVM directory to your path, so that the build system of Solang can find the correct version of LLVM to use.
Linux
~~~~~
A pre-built version of LLVM, specifically configured for Solang, is available at
`<https://github.com/hyperledger/solang/releases/download/v0.2.1/llvm14.0-linux-x86-64.tar.xz>`_ for x86 processors
and at `<https://github.com/hyperledger/solang/releases/download/v0.2.1/llvm14.0-linux-arm64.tar.xz>`_ for ARM.
After downloading, untar the file in a terminal and add it to your path.
.. code-block:: bash
tar Jxf llvm14.0-linux-x86-64.tar.xz
export PATH=$(pwd)/llvm14.0/bin:$PATH
Windows
~~~~~~~
A pre-built version of LLVM, specifically configured for Solang, is available at
`<https://github.com/hyperledger/solang/releases/download/v0.2.1/llvm14.0-win.zip>`_.
After unzipping the file, add the bin directory to your path.
.. code-block:: batch
set PATH=%PATH%;C:\llvm14.0\bin
Mac
~~~
A pre-built version of LLVM for intel macs, is available at
`<https://github.com/hyperledger/solang/releases/download/v0.2.1/llvm14.0-mac-intel.tar.xz>`_ and for arm macs there is
`<https://github.com/hyperledger/solang/releases/download/v0.2.1/llvm14.0-mac-arm.tar.xz>`_. After downloading,
untar the file in a terminal and add it to your path like so:
.. code-block:: bash
tar Jxf llvm14.0-mac-arm.tar.xz
xattr -rd com.apple.quarantine llvm14.0
export PATH=$(pwd)/llvm14.0/bin:$PATH
Building LLVM from source
~~~~~~~~~~~~~~~~~~~~~~~~~
The LLVM project itself has a guide to `installing from source <http://www.llvm.org/docs/CMake.html>`_ which
you may need to consult. First if all clone our LLVM repository:
.. code-block:: bash
git clone --depth 1 --branch solana-rustc/14.0-2022-03-22 https://github.com/solana-labs/llvm-project
cd llvm-project
Now run cmake to create the makefiles. Replace the *installdir* argument to ``CMAKE_INSTALL_PREFIX`` with with a directory where you would like to have LLVM installed, and then run the build:
.. code-block:: bash
cmake -G Ninja -DLLVM_ENABLE_ASSERTIONS=On '-DLLVM_ENABLE_PROJECTS=clang;lld' \
-DLLVM_ENABLE_TERMINFO=Off -DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=installdir -B build llvm
cmake --build build --target install
Once the build has succeeded, the *installdir*/bin has to be added to your path so the
Solang build can find the ``llvm-config`` from this build:
.. code-block:: bash
export PATH=installdir/bin:$PATH
And on Windows, assuming *installdir* was ``C:\Users\User\solang-llvm``:
.. code-block:: batch
set PATH=%PATH%;C:\Users\User\solang-llvm\bin
Step 2: Build Solang
____________________
Once you have the correct LLVM version in your path, simply run:
.. code-block:: bash
git clone https://github.com/hyperledger/solang/
cd solang
cargo build --release
The executable will be in ``target/release/solang``.
Alternative step 2: Build Solang from crates.io
_______________________________________________
The latest Solang release is on `crates.io <https://crates.io/crates/solang>`_. Once you have the
correct LLVM version in your path, simply run:
.. code-block:: bash
cargo install solang
