riscv
/
coriolis
mirror of https://gitlab.lip6.fr/vlsi-eda/coriolis.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge INSTALL.rst into README

This commit is contained in:
Rob Taylor 2023-10-14 23:19:34 +01:00 committed by Rob Taylor
parent 98186cacc2
commit 4e62c8689a
3 changed files with 172 additions and 384 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

161
INSTALL.rst
View File

@ -1,161 +0,0 @@
Building Coriolis
=================
Ubuntu/Windows WSL2 Build Environment
=====================================
If you haven't already got them, install `build-essential` and `git`
.. code-block:: bash
sudo apt install build-essential git ccache
Clone the repo:
.. code-block:: bash
git clone --recurse-submodules https://github.com/lip6/coriolis
cd coriolis
Install the build dependencies:
.. code-block:: bash
sudo apt install python3 python3-pip python3.10-venv \
doxygen pelican texlive-latex-recommended \
bison flex \
qtbase5-dev libqt5svg5-dev libqwt-qt5-dev libbz2-dev \
rapidjson-dev libboost-all-dev libeigen3-dev libxml2-dev
Mac OSX Build Environment
=========================
To build on Mac, first install _Homebrew: https://brew.sh. Be sure to follow all the instructions it gives after install so HOMEBREW_PREFIX gets set!
Clone the repo:
.. code-block:: bash
git clone --recurse-submodules https://github.com/lip6/coriolis
cd coriolis
To install the prereqisites:
.. code-block:: bash
brew install ccache doxygen pelican qt@5 qwt-qt5 rapidjson boost eigen
brew install --cask mactex
We need to set some environment variables for finding the cask only components. We use dotenv to set these in the PDM venv (see below)
.. code-block:: bash
pip install dotenv
dotenv set CMAKE_FRAMEWORK_PATH "$HOMEBREW_PREFIX/opt/qt@5/lib/cmake/"
dotenv set PKG_CONFIG_PATH "$HOMEBREW_PREFIX/opt/qt@5/lib/pkgconfig:$HOMEBREW_PREFIX/opt/qwt-qt5/lib/pkgconfig"
Building Coriolis
=================
To build Python wheels, you'll need the `build` package if you don't already have it installed:
.. code-block:: bash
pip3 install build
.. code-block:: bash
python3 -m build -w
The wheels can be found in dist and installed using pip:
.. code-block:: bash
pip3 install dist/*.whl
Development environment
=======================
For day-to-day development, its currently best to use meson and ninja directly. Currently there are `issues with using a Python editable install`_.
We use PDM_ to manage our development environment, which uses Python's venv_ system.
.. code-block:: bash
pip install pdm
Before starting, you'll likely want to install the `shell completion`_ and read about `using pdm with virtual environments`_. The basics are very simple, you just use pdm to run the build commands in an environment it automatially handles.
First we set up our pdm virtual environment:
.. code-block:: bash
pdm install --no-self -d --plugins
Below we are just using a local directory call builddir for our meson_ build directory, but you can put it wherever you like.
.. code-block:: bash
pdm run meson setup builddir
pdm run ninja -C builddir install
You can then use `pdm run` to run any programs or scripts dependant on Coriolis, for example:
.. code-block:: bash
pdm run unittests/python/test_hurricane.py
You can also install locally using:
.. code-block:: bash
pdm run meson setup builddir -Dpython.install_env=system
pdm run ninja -C builddir install
For more configuration and install options, see:
.. code-block:: bash
pdm run meson configure
.. _issues with using a Python editable install: https://github.com/lip6/coriolis/issues/67
.. _venv: https://www.dataquest.io/blog/a-complete-guide-to-python-virtual-environments/#how-to-use-python-environments
.. _shell completion: https://pdm.fming.dev/latest/#shell-completion
.. _using pdm with virtual environments: https://pdm.fming.dev/latest/usage/venv/
Other operating systems
=======================
Coriolis is currently tested on CentOS 7 (via manylinux 2014), latest Ubuntu and on MacOSX.
We welcome patches for other operating systems, though please add appropriate CI!
You'll need the following prerequisites:
* A C++11 compliant compiler.
* Python 3.9 or later
* Pip
* ninja.
* bzip2
* boost
* bison & flex.
* Qt 5 & Qt 5 Svg.
* Qwt
* libxml2.
* RapidJSON, http://rapidjson.org/ .
* Eigen 3, http://eigen.tuxfamily.org .
* doxygen
* pelican
* latex

167
README.rst
View File

@ -55,10 +55,177 @@ Installation
Python 3.7 or later is required to use Coliolis. It can then be installed from `Pypi <https://pypi.org/>`_.
.. code-block:: bash
pip3 install coriolis-eda
Note for Windows, we currently only support running under WSL2.
=================
Building Coriolis
=================
Most folk will only need to install using pip, but if you want to develop or need to build from scratch, read on!
Ubuntu/Windows WSL2 Build Environment
=====================================
If you haven't already got them, install `build-essential` and `git`
.. code-block:: bash
sudo apt install build-essential git ccache
Clone the repo:
.. code-block:: bash
git clone --recurse-submodules https://github.com/lip6/coriolis
cd coriolis
Install the build dependencies:
.. code-block:: bash
sudo apt install python3 python3-pip python3.10-venv \
doxygen pelican texlive-latex-recommended \
bison flex \
qtbase5-dev libqt5svg5-dev libqwt-qt5-dev libbz2-dev \
rapidjson-dev libboost-all-dev libeigen3-dev libxml2-dev
Mac OSX Build Environment
=========================
To build on Mac, first install _Homebrew: https://brew.sh. Be sure to follow all the instructions it gives after install so HOMEBREW_PREFIX gets set!
Clone the repo:
.. code-block:: bash
git clone --recurse-submodules https://github.com/lip6/coriolis
cd coriolis
To install the prereqisites:
.. code-block:: bash
brew install ccache doxygen pelican qt@5 qwt-qt5 rapidjson boost eigen
brew install --cask mactex
We need to set some environment variables for finding the cask only components. We use dotenv to set these in the PDM venv (see below)
.. code-block:: bash
pip install python-dotenv
dotenv set CMAKE_FRAMEWORK_PATH "$HOMEBREW_PREFIX/opt/qt@5/lib/cmake/"
dotenv set PKG_CONFIG_PATH "$HOMEBREW_PREFIX/opt/qt@5/lib/pkgconfig:$HOMEBREW_PREFIX/opt/qwt-qt5/lib/pkgconfig"
Building Coriolis
=================
To build Python wheels, you'll need the `build` package if you don't already have it installed:
.. code-block:: bash
pip3 install build
.. code-block:: bash
python3 -m build -w
The wheels can be found in dist and installed using pip:
.. code-block:: bash
pip3 install dist/*.whl
Development environment
=======================
For day-to-day development, its currently best to use meson and ninja directly. Currently there are `issues with using a Python editable install`_.
We use PDM_ to manage our development environment, which uses Python's venv_ system.
.. code-block:: bash
pip install pdm
Before starting, you'll likely want to install the `shell completion`_ and read about `using pdm with virtual environments`_. The basics are very simple, you just use pdm to run the build commands in an environment it automatially handles.
First we set up our pdm virtual environment:
.. code-block:: bash
pdm install --no-self -d --plugins
Below we are just using a local directory call builddir for our meson_ build directory, but you can put it wherever you like.
.. code-block:: bash
pdm run meson setup builddir
pdm run ninja -C builddir install
You can then use `pdm run` to run any programs or scripts dependant on Coriolis, for example:
.. code-block:: bash
pdm run unittests/python/test_hurricane.py
You can also install locally using:
.. code-block:: bash
pdm run meson setup builddir -Dpython.install_env=system
pdm run ninja -C builddir install
For more configuration and install options, see:
.. code-block:: bash
pdm run meson configure
.. _issues with using a Python editable install: https://github.com/lip6/coriolis/issues/67
.. _venv: https://www.dataquest.io/blog/a-complete-guide-to-python-virtual-environments/#how-to-use-python-environments
.. _shell completion: https://pdm.fming.dev/latest/#shell-completion
.. _using pdm with virtual environments: https://pdm.fming.dev/latest/usage/venv/
Other operating systems
=======================
Coriolis is currently tested on CentOS 7 (via manylinux 2014), latest Ubuntu and on MacOSX.
We welcome patches for other operating systems, though please add appropriate CI!
You'll need the following prerequisites:
* A C++11 compliant compiler.
* Python 3.9 or later
* Pip
* ninja.
* bzip2
* boost
* bison & flex.
* Qt 5 & Qt 5 Svg.
* Qwt
* libxml2.
* RapidJSON, http://rapidjson.org/ .
* Eigen 3, http://eigen.tuxfamily.org .
* doxygen
* pelican
* latex
Documentation
=============

228
documentation/content/pages/users-guide/Installation.rst
View File

@ -4,234 +4,16 @@
Installation
============
.. note::
As the sources are being released, the binary packaging is dropped.
You may still find (very) old versions here: http://asim.lip6.fr/pub/coriolis/2.0 .
In a nutshell, building source consists in pulling the |git| repository then
running the |ccb| installer.
.. note::
The documentation is already generated and commited in the |git| tree.
You may not install the additional prerequisites for the documentation.
By default the documentation is not generated, just installed by |ccb|.
If you really want to re-generate it, add the ``--doc`` flag to |ccb|.
Main building prerequisites:
* cmake
* C++11-capable compiler
* BFD library (provided through ``binutils``).
* RapidJSON_
* python2.7
* boost
* libxml2
* bzip2
* yacc & lex
* Qt 4 or Qt 5
* PyQt 4 or PyQt 5
* Qwt 6
Building documentation prerequisites:
* doxygen
* latex
* python-docutils (for reStructuredText)
* pelican
The following libraries get directly bundled with |Coriolis|:
* LEF/DEF (from Si2_)
* FLUTE (from `Chris C. N. Chu <http://home.eng.iastate.edu/~cnchu/flute.html>`_)
For other distributions, refer to their own packaging system.
We reccomend installing directly from Pypi <https://pypi.org/>`_. First install Python 3.9 or later as appropriate for your system, then:
Fixed Directory Tree
~~~~~~~~~~~~~~~~~~~~
In order to simplify the work of the |ccb| installer, the source, build
and installation tree is fixed. To successfully compile |Coriolis| you must
follow it exactly. The tree is relative to the home directory of the user
building it (note :fboxtt:`~/` or :fboxtt:`$HOME/`). Only the source
directory needs to be manually created by the user, all others will be
automatically created either by |ccb| or the build system.
+--------------------------------------------------------------------------------------------------------------+
| **Sources** |
+------------------------------+-------------------------------------------------------------------------------+
| | Sources root | | ~/coriolis-2.x/src |
| | **under git** | | ~/coriolis-2.x/src/coriolis |
+------------------------------+-------------------------------------------------------------------------------+
| **Architecture Dependant Build** |
+------------------------------+-------------------------------------------------------------------------------+
| | Linux, SL 7, 64b | | ~/coriolis-2.x/Linux.el7_64/Release.Shared/build/<tool> |
| | Linux, SL 6, 32b | | ~/coriolis-2.x/Linux.slsoc6x/Release.Shared/build/<tool> |
| | Linux, SL 6, 64b | | ~/coriolis-2.x/Linux.slsoc6x_64/Release.Shared/build/<tool> |
| | Linux, Fedora, 64b | | ~/coriolis-2.x/Linux.fc_64/Release.Shared/build/<tool> |
| | Linux, Fedora, 32b | | ~/coriolis-2.x/Linux.fc/Release.Shared/build/<tool> |
| | FreeBSD 8, 32b | | ~/coriolis-2.x/FreeBSD.8x.i386/Release.Shared/build/<tool> |
| | FreeBSD 8, 64b | | ~/coriolis-2.x/FreeBSD.8x.amd64/Release.Shared/build/<tool> |
| | Windows 7, 32b | | ~/coriolis-2.x/Cygwin.W7/Release.Shared/build/<tool> |
| | Windows 7, 64b | | ~/coriolis-2.x/Cygwin.W7_64/Release.Shared/build/<tool> |
| | Windows 8.x, 32b | | ~/coriolis-2.x/Cygwin.W8/Release.Shared/build/<tool> |
| | Windows 8.x, 64b | | ~/coriolis-2.x/Cygwin.W8_64/Release.Shared/build/<tool> |
+------------------------------+-------------------------------------------------------------------------------+
| **Architecture Dependant Install** |
+------------------------------+-------------------------------------------------------------------------------+
| Linux, SL 6, 32b | ~/coriolis-2.x/Linux.slsoc6x/Release.Shared/install/ |
+------------------------------+-------------------------------------------------------------------------------+
| **FHS Compliant Structure under Install** |
+------------------------------+-------------------------------------------------------------------------------+
| | Binaries | | .../install/bin |
| | Libraries (Python) | | .../install/lib |
| | Include by tool | | .../install/include/coriolis2/<project>/<tool> |
| | Configuration files | | .../install/etc/coriolis2/ |
| | Doc, by tool | | .../install/share/doc/coriolis2/en/html/<tool> |
+------------------------------+-------------------------------------------------------------------------------+
.. note:: *Alternate build types:* the ``Release.Shared`` means an optimized build
with shared libraries. But there are also available ``Static`` instead of ``Shared``
and ``Debug`` instead of ``Release`` and any combination of them.
``Static`` does not work because I don't know yet to mix statically linked binaries
and Python modules (which must be dynamic).
.. code-block:: bash
pip3 install coriolis-eda
Building Coriolis
~~~~~~~~~~~~~~~~~
Building from Source
====================
The actively developed branch
-----------------------------
The **devel_anabatic** branch is now closed and we go back to a more classical
scheme where **master** is the stable version and **devel** the development one.
The |Coriolis| |git| repository is https://github.com/lip6/coriolis.git
.. note::
Again, the **devel_anabatic** branch is now closed. Please revert to **devel**
or **master**.
.. note::
As it is now possible to mix |PyQt| widget with |Coriolis| ones, it is simpler
for us to revert to |Qt| 4 only. Our reference |OS| being |RHEL| 7, there is no
compatible |PyQt5| build compatible with their |Qt| 5 version (we fall short of
one minor, they provides |Qt| 5.9 were we need at least |Qt| 5.10).
.. note::
Under |RHEL| 7 or clones, they upgraded their version of |Qt| 4 (from 4.6 to 4.8)
so the *diagonal line* bug no longer occurs. So we can safely use the default
system |Qt| again.
Installing on |RedHat| or compatible distributions
--------------------------------------------------
1. Install or check that the required prerequisites are installed :
.. code-block:: bash
dummy@lepka:~> yum install -y git cmake bison flex gcc-c++ libstdc++-devel \
binutils-devel \
boost-devel boost-python boost-filesystem \
boost-regex boost-wave \
python-devel libxml2-devel bzip2-devel \
qt-devel
The packages ``qwt`` and ``qwt-devel`` are not provided by any standard repository
(like |EPEL|). You may download them from the
`LIP6 Addons Repository <https://ftp.lip6.fr/pub/linux/distributions/slsoc/soc/7/addons/x86_64/repoview/letter_q.group.html>`_
Then run:
.. code-block:: sh
dummy@lepka:~> yum localinstall -y qwt-6.1.2-4.fc23.x86_64.rpm \
qwt-devel-6.1.2-4.fc23.x86_64.rpm # Qwt for Qt 4.
You may also install them directly (whithout an intermediate download):
.. code-block:: sh
dummy@lepka:~> yum install -y http://ftp.lip6.fr/pub/linux/distributions/slsoc/soc/7/addons/x86_64/RPMS/qwt-6.1.2-4.fc23.x86_64.rpm \
http://ftp.lip6.fr/pub/linux/distributions/slsoc/soc/7/addons/x86_64/RPMS/qwt-devel-6.1.2-4.fc23.x86_64.rpm
2. Install the unpackaged prerequisites. Currently, only RapidJSON_.
.. code-block:: sh
dummy@lepka:~> mkdir -p ~/coriolis-2.x/src/support
dummy@lepka:support> cd ~/coriolis-2.x/src/support
dummy@lepka:support> git clone http://github.com/miloyip/rapidjson
3. Create the source directory and pull the |git| repository:
.. code-block:: sh
dummy@lepka:~> mkdir -p ~/coriolis-2.x/src
dummy@lepka:src> cd ~/coriolis-2.x/src
dummy@lepka:src> git clone https://github.com/lip6/coriolis.git
4. Build & install:
.. code-block:: sh
dummy@lepka:src> cd coriolis
dummy@lepka:coriolis> git checkout devel
dummy@lepka:coriolis> ./bootstrap/ccb.py --project=support \
--project=coriolis \
--make="-j4 install"
.. note::
Pre-generated documentation will get installed by the previous command.
Only if you did made modifications to it you need to regenerate it with:
.. code-block:: sh
dummy@lepka:coriolis> ./bootstrap/ccb.py --project=support \
--project=coriolis \
--doc --make="-j1 install"
We need to perform a separate installation of the documentation because it
does not support to be generated with a parallel build. So we compile & install in a first
stage in ``-j4`` (or whatever) then we generate the documentation in ``-j1``
Under |RHEL6| or clones, you must build using the |devtoolset|, the version is to
be given as argument:
.. code-block:: sh
dummy@lepka:coriolis> ./bootstrap/ccb.py --project=coriolis \
--devtoolset=8 --make="-j4 install"
If you want to use Qt 5 instead of Qt 4, modify the previous steps as follows:
* At **step 1**, do not install the |QT| 4 related development package (``qt4-devel``),
but instead:
.. code-block:: sh
dummy@lepka:~> yum install -y qt5-qtbase-devel qt5-qtsvg-devel # Qt 5.
The package ``qwt-qt5-devel`` and it's dependency ``qwt-qt5`` are not provided
by any standard repository (like |EPEL|). You may download them from the
`LIP6 Addons Repository <https://ftp.lip6.fr/pub/linux/distributions/slsoc/soc/7/addons/x86_64/repoview/letter_q.group.html>`_
Then run:
.. code-block:: sh
dummy@lepka:~> yum localinstall -y qwt-qt5-6.1.2-4.fc23.x86_64.rpm \
qwt-qt5-devel-6.1.2-4.fc23.x86_64.rpm # Qwt for Qt 5.
* At **step 4**, add a ``--qt5`` argument to the ``ccb.py`` command line.
* The |Python| scripts that make use of |PyQt| in ``crlcore`` and ``cumulus`` must be
edited to import ``PyQt5`` instead of ``PtQt4`` (should find a way to automatically
switch between the two of them).
The complete list of |ccb| functionalities can be accessed with the ``--help`` argument.
It also may be run in graphical mode (``--gui``).
Building a Debug Enabled Version