====== Installing actflow  ======

Primary development of the tools in the actflow repository is conducted on Linux and MacOS, and so it has been extensively tested on such systems. It has also been tested in certain [[install#Microsoft Windows|Windows]] environments (see below).

The repository is available from [[https://github.com/asyncvlsi/actflow|Github]]. Once you clone this repository, make sure you run 
<code>
$ git submodule update --init --recursive
</code>
This will bring in all the components needed.

===== Linux/Unix-like environments =====

Before starting, please make sure that your system satisfies the following requirements:

   * The system must have libedit installed.
      * For the ''yum'' package manager, the package is called ''libedit-devel''
      * For ''apt-get'', it is ''libeditline-dev'' or ''libedit-dev''
      * Some systems have both packages. In that case please use ''libedit'', not ''libeditline''.
   * The system must have ''zlib'' installed
   * The system must have the macro pre-processing package ''m4'' installed
   * The system must have a modern C++ compiler (at least C++-17)
   * The system must have ''cmake'' (at least version 3.16)
   * The system must have the Boost libraries (at least version 1.71.0)
   * The system must have ''libfmt'' (at least version 4.0)

**MacOS:** These packages can be installed using the [[https://brew.sh/|homebrew]] package manager. Note that on recent versions of MacOS, the C++ compiler provided by Apple does not accept the ''-fopenmp'' flag for OpenMP compilation, so you will likely need to install g++ using homebrew as well.

==== Build instructions ====

Create a directory where you'd like the tools to be installed. Example common locations include ''/usr/local/cad'', ''/opt/cad'', ''/opt/async''. Once you've cloned the [[http://github.com/asyncvlsi/actflow|git repo]] and pulled in the submodules:

   * Set the environment variable ''ACT_HOME'' to point to the install directory.
   * Run ''./build''. This should build and install all the tools.

If there is an issue building the software and you want to do a clean build, use ''./clean'' before re-running the build instructions above.

Once you've built the tools, run ''./run.sh'' to run through a set of basic test cases.

Note that  the environment variable ''ACT_HOME'' has to be set to run the ACT tools, so it is best to set it in your ''.bashrc'' or the appropriate initialization script read in by your default shell.

Optional: to add the tools to your path add ''export PATH=$ACT_HOME/bin:$PATH'' to your ''.bashrc'' too


**actsim and Xyce:** The ACT simulator also supports mixed analog/digital simulation using "Xyce". To include this feature, follow the instructions above. After that, follow the instructions provided by the [[https://github.com/asyncvlsi/actsim|''actsim'']] repository to re-build and re-install ''actsim''.



===== Microsoft Windows =====

Recent versions of Windows include compatibility layers for Unix, and ACT has been successfully tested in such an environment.

[[windows_build|Some instructions for running ACT tools on Microsoft Windows]]



===== Troubleshooting =====

If you have trouble building on your specific operating system have a peek in the continuous integration scripts of the git repository if your operating system is covered there and you can try the commands specified:

https://github.com/asyncvlsi/actflow/blob/main/.circleci/config.yml

for ''Debian'', ''Ubuntu'' look at the ubuntu section. Here's the script used by the continuous integration build on Ubuntu to build and install the tools in ''/usr/local/cad'', and run the test cases:
<code>
$ apt-get -q update -y
$ apt-get -q install -y libedit-dev zlib1g-dev m4 build-essential cmake libfmt-dev git libboost-all-dev libopenmpi-dev llvm flex bison
$ git clone https://github.com/asyncvlsi/actflow
$ cd actflow
$ git submodule update --init --recursive
$ mkdir /usr/local/cad
$ export ACT_HOME=/usr/local/cad
$ ./build && ./run.sh
</code>

Replace ''/usr/local/cad'' on the lines where it is used with your actual installation directory. 

For Alpine Linux look at the alpine section in the yml file.

**MacOS:** Recent versions of MacOS have a C++ compiler issue, namely that the default compiler distributed by Apple does not support the "-fopenmp" flag. To fix this issue, we normally install either ''llvm'' or ''g++'' using homebrew. This normally results in the compiler being installed in a path that looks something like ''/opt/homebrew/Cellar/llvm/<version>/bin/clang++'' or ''/opt/homebrew/Cellar/gcc/<version>/bin/g++-<version>''. Set the environment variable ''CXX'' to the absolute path name of this C++ compiler before running "./build".

=== OpenMP message ===

You may see the following message:
<code>
Could not find a C++ compiler that supports -fopenmp
Please set environment variable CXX to a C++ compiler that does.
Note: modern LLVM and GNU compilers support this option; if you
are on a Mac, installing LLVM using homebrew (brew install llvm)
and setting CXX to be the path to the resulting clang++ should work.
</code>

This means that the build script could not find a C++ compiler that could successfully compile the following program:
<code>
#include <omp.h>

int main (void)
{
  return 0;
}
</code>
A modern install of g++ or clang++ can compile this program when given the ''-fopenmp'' option.

=== Filesystem message ===

You may see the following message:

<code>
C++ compiler does not directly support std::filesystem.
Please set environment variable CXX to a C++ compiler that does.
</code>

This means that your C++ compiler could not compile and link the following program:

<code>
#include <filesystem>

int main (void)
{
  std::filesystem::path tst {".."};
  return 0;
}
</code>

Tie build script tries to compile this with and without the ''-lstdc++fs'' option (needed for some older C++ compilers, but no longer needed in a modern compiler). This message means both options did not succeed using the compiler that supported the ''-fopenmp'' flag.