diff --git a/INSTALL.rst b/INSTALL.rst deleted file mode 100644 index 42ae979e..00000000 --- a/INSTALL.rst +++ /dev/null @@ -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 - - - diff --git a/README.rst b/README.rst index 336de86e..eec3284a 100644 --- a/README.rst +++ b/README.rst @@ -55,10 +55,177 @@ Installation Python 3.7 or later is required to use Coliolis. It can then be installed from `Pypi `_. .. 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 ============= diff --git a/documentation/content/pages/users-guide/Installation.rst b/documentation/content/pages/users-guide/Installation.rst index 2969c75c..16224a0f 100644 --- a/documentation/content/pages/users-guide/Installation.rst +++ b/documentation/content/pages/users-guide/Installation.rst @@ -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 `_) - -For other distributions, refer to their own packaging system. +We reccomend installing directly from Pypi `_. 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/ | -| | Linux, SL 6, 32b | | ~/coriolis-2.x/Linux.slsoc6x/Release.Shared/build/ | -| | Linux, SL 6, 64b | | ~/coriolis-2.x/Linux.slsoc6x_64/Release.Shared/build/ | -| | Linux, Fedora, 64b | | ~/coriolis-2.x/Linux.fc_64/Release.Shared/build/ | -| | Linux, Fedora, 32b | | ~/coriolis-2.x/Linux.fc/Release.Shared/build/ | -| | FreeBSD 8, 32b | | ~/coriolis-2.x/FreeBSD.8x.i386/Release.Shared/build/ | -| | FreeBSD 8, 64b | | ~/coriolis-2.x/FreeBSD.8x.amd64/Release.Shared/build/ | -| | Windows 7, 32b | | ~/coriolis-2.x/Cygwin.W7/Release.Shared/build/ | -| | Windows 7, 64b | | ~/coriolis-2.x/Cygwin.W7_64/Release.Shared/build/ | -| | Windows 8.x, 32b | | ~/coriolis-2.x/Cygwin.W8/Release.Shared/build/ | -| | Windows 8.x, 64b | | ~/coriolis-2.x/Cygwin.W8_64/Release.Shared/build/ | -+------------------------------+-------------------------------------------------------------------------------+ -| **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// | -| | Configuration files | | .../install/etc/coriolis2/ | -| | Doc, by tool | | .../install/share/doc/coriolis2/en/html/ | -+------------------------------+-------------------------------------------------------------------------------+ - -.. 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 `_ - 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 `_ - 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