riscv
/
yosys
mirror of https://github.com/YosysHQ/yosys.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
yosys/docs/source/getting_started/installation.rst

218 lines
7.5 KiB
ReStructuredText
Raw Normal View History

Reorganising documentation Also changing to furo theme.
2023-08-02 16:20:29 -05:00
Installation
------------
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
This document will guide you through the process of installing Yosys.
CAD suite(s)
~~~~~~~~~~~~
Yosys is part of the `Tabby CAD Suite
<https://www.yosyshq.com/tabby-cad-datasheet>`_ and the `OSS CAD Suite
<https://github.com/YosysHQ/oss-cad-suite-build>`_! The easiest way to use yosys
is to install the binary software suite, which contains all required
dependencies and related tools.
* `Contact YosysHQ <https://www.yosyshq.com/contact>`_ for a `Tabby CAD Suite
<https://www.yosyshq.com/tabby-cad-datasheet>`_ Evaluation License and
download link
* OR go to https://github.com/YosysHQ/oss-cad-suite-build/releases to download
the free OSS CAD Suite
* Follow the `Install Instructions on GitHub
<https://github.com/YosysHQ/oss-cad-suite-build#installation>`_
Make sure to get a Tabby CAD Suite Evaluation License if you need features such
as industry-grade SystemVerilog and VHDL parsers!
For more information about the difference between Tabby CAD Suite and the OSS
CAD Suite, please visit https://www.yosyshq.com/tabby-cad-datasheet
Many Linux distributions also provide Yosys binaries, some more up to date than
others. Check with your package manager!
Targeted architectures
^^^^^^^^^^^^^^^^^^^^^^
The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
TODOs Blocking tasks are now capital TODO (compared to non-blocking todo). Updated some of the todos. Added note about which intel synth does which families. Rename extended Yosys universe to Yosys family. Added brief text to landing page, and also a note about the restructure and where to find old docs. Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header). Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-11 17:05:45 -06:00
.. only:: html
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
TODOs Blocking tasks are now capital TODO (compared to non-blocking todo). Updated some of the todos. Added note about which intel synth does which families. Rename extended Yosys universe to Yosys family. Added brief text to landing page, and also a note about the restructure and where to find old docs. Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header). Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-11 17:05:45 -06:00
- linux-x64 |linux-x64|
- Most personal Linux based computers
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
TODOs Blocking tasks are now capital TODO (compared to non-blocking todo). Updated some of the todos. Added note about which intel synth does which families. Rename extended Yosys universe to Yosys family. Added brief text to landing page, and also a note about the restructure and where to find old docs. Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header). Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-11 17:05:45 -06:00
- darwin-x64 |darwin-x64|
docs: Update OSS CAD suite info
2024-03-17 16:45:31 -05:00
- macOS 12 or later with Intel CPU
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
TODOs Blocking tasks are now capital TODO (compared to non-blocking todo). Updated some of the todos. Added note about which intel synth does which families. Rename extended Yosys universe to Yosys family. Added brief text to landing page, and also a note about the restructure and where to find old docs. Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header). Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-11 17:05:45 -06:00
- darwin-arm64 |darwin-arm64|
docs: Update OSS CAD suite info
2024-03-17 16:45:31 -05:00
- macOS 12 or later with M1/M2 CPU
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
TODOs Blocking tasks are now capital TODO (compared to non-blocking todo). Updated some of the todos. Added note about which intel synth does which families. Rename extended Yosys universe to Yosys family. Added brief text to landing page, and also a note about the restructure and where to find old docs. Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header). Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-11 17:05:45 -06:00
- windows-x64 |windows-x64|
docs: Update OSS CAD suite info
2024-03-17 16:45:31 -05:00
- Targeted for Windows 10 and 11
TODOs Blocking tasks are now capital TODO (compared to non-blocking todo). Updated some of the todos. Added note about which intel synth does which families. Rename extended Yosys universe to Yosys family. Added brief text to landing page, and also a note about the restructure and where to find old docs. Moved todolist above ToC in preparation for disabling it in the config (so that it doesn't need it's own header). Fixed pdf build, was previously breaking on trying to include the svg badges.
2023-12-11 17:05:45 -06:00
- linux-arm64 |linux-arm64|
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
.. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build
.. _nightly builds: https://github.com/YosysHQ/oss-cad-suite-build/releases/latest
.. |linux-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-x64.yml/badge.svg
.. |darwin-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-x64.yml/badge.svg
.. |darwin-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-arm64.yml/badge.svg
.. |windows-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/windows-x64.yml/badge.svg
.. |linux-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm64.yml/badge.svg
Building from source
~~~~~~~~~~~~~~~~~~~~
Refer to the `readme`_ for the most up-to-date install instructions.
.. _readme: https://github.com/YosysHQ/yosys#building-from-source
docs: Moving 011 into main body of manual Mostly in the `more_scripting` section, with part of the intro in the `scripting_intro`. Also includes an extra todo on the installation page and some extra notes on where to find `show` details where relevant.
2023-10-09 18:27:00 -05:00
Reorganising documentation Also changing to furo theme.
2023-08-02 16:20:29 -05:00
Supported platforms
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
^^^^^^^^^^^^^^^^^^^
The following platforms are supported and regularly tested:
- Linux
- macOS
Other platforms which may work, but instructions may not be up to date and are
not regularly tested:
- FreeBSD
- WSL
- Windows with (e.g.) Cygwin
Build prerequisites
^^^^^^^^^^^^^^^^^^^
Update documentation for C++17 switch
2024-06-17 10:08:13 -05:00
A C++ compiler with C++17 support is required as well as some standard tools
Docs: changes/todos from JF
2024-01-29 18:33:07 -06:00
such as GNU Flex, GNU Bison, Make and Python. Some additional tools: readline,
libffi, Tcl and zlib; are optional but enabled by default (see
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
Docs: Shorten cmd:ref
2024-05-02 20:16:48 -05:00
`show` command to display schematics.
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
Installing all prerequisites for Ubuntu 20.04:
.. code:: console
Add lld to clang build environments and Dockerfile
2024-07-22 14:33:46 -05:00
sudo sudo apt-get install build-essential clang lld bison flex \
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
libreadline-dev gawk tcl-dev libffi-dev git make \
graphviz xdot pkg-config python3 libboost-system-dev \
libboost-python-dev libboost-filesystem-dev zlib1g-dev
Installing all prerequisites for macOS 11 (with Homebrew):
.. code:: console
brew install bison flex gawk libffi git graphviz \
pkg-config python3 tcl-tk xdot bash boost-python3
Running the build system
^^^^^^^^^^^^^^^^^^^^^^^^
docs: Clarify install instructions `config-clang` is the default, and doesn't need to be run first. Previous instructions were ambiguous about that point. Add note on using a different `CXX`.
2024-03-17 16:35:01 -05:00
From the root `yosys` directory, call the following commands:
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
.. code:: console
make
sudo make install
docs: Clarify install instructions `config-clang` is the default, and doesn't need to be run first. Previous instructions were ambiguous about that point. Add note on using a different `CXX`.
2024-03-17 16:35:01 -05:00
This will build and then install Yosys, making it available on the command line
as `yosys`. Note that this also downloads, builds, and installs `ABC`_ (using
Docs: tidying - Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width.
2024-01-29 18:31:00 -06:00
:program:`yosys-abc` as the executable name).
.. _ABC: https://github.com/berkeley-abc/abc
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
docs: Clarify install instructions `config-clang` is the default, and doesn't need to be run first. Previous instructions were ambiguous about that point. Add note on using a different `CXX`.
2024-03-17 16:35:01 -05:00
The default compiler is ``clang``, to change between ``clang`` and ``gcc``, use
one of the following:
.. code:: console
make config-clang
make config-gcc
To use a compiler different than the default, use:
.. code:: console
make CXX="g++-11"
Updates to install and tests Includes CAD suite info and details on the OSS CAD suite nightly build targets. Instructions for building from source, largely based on the readme but with some minor modifications. Tests are still WIP, but we replaced the old test suites with a brief comment on the github workflow tests. Still needs more on the tests themselves and how to run them locally. Also an extra todo on the index page.
2023-12-10 17:44:05 -06:00
.. seealso::
Docs: Update build_verific Clarify partially supported builds section. Update parameter defaults. Include note on finding compile options with `yosys-config`. Fix remaining references to `/yosys_source/`.
2024-08-21 17:03:59 -05:00
Refer to :doc:`/yosys_internals/extending_yosys/test_suites` for details on
testing Yosys once compiled.
Reorganising documentation Also changing to furo theme.
2023-08-02 16:20:29 -05:00
Source tree and build system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Yosys source tree is organized into the following top-level
directories:
Docs: installation/source tree
2024-01-17 18:52:32 -06:00
``backends/``
This directory contains a subdirectory for each of the backend modules.
``docs/``
Contains the source for this documentation, including images and sample code.
``examples/``
Contains example code for using Yosys with some other tools including a demo
of the Yosys Python api, and synthesizing for various toolchains such as
Intel and Anlogic.
``frontends/``
This directory contains a subdirectory for each of the frontend modules.
``guidelines/``
Contains developer guidelines, including the code of conduct and coding style
guide.
``kernel/``
This directory contains all the core functionality of Yosys. This includes
the functions and definitions for working with the RTLIL data structures
Docs: tidying - Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width.
2024-01-29 18:31:00 -06:00
(:file:`rtlil.{h|cc}`), the ``main()`` function (:file:`driver.cc`), the
internal framework for generating log messages (:file:`log.{h|cc}`), the
internal framework for registering and calling passes
(:file:`register.{h|cc}`), some core commands that are not really passes
(:file:`select.cc`, :file:`show.cc`, …) and a couple of other small utility
libraries.
Docs: installation/source tree
2024-01-17 18:52:32 -06:00
``libs/``
Libraries packaged with Yosys builds are contained in this folder. See
:doc:`/appendix/auxlibs`.
``misc/``
Other miscellany which doesn't fit anywhere else.
``passes/``
This directory contains a subdirectory for each pass or group of passes. For
Docs: tidying - Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width.
2024-01-29 18:31:00 -06:00
example as of this writing the directory :file:`passes/hierarchy/` contains the
Docs: Shorten cmd:ref
2024-05-02 20:16:48 -05:00
code for three passes: `hierarchy`, `submod`, and
`uniquify`.
Docs: installation/source tree
2024-01-17 18:52:32 -06:00
``techlibs/``
This directory contains simulation models and standard implementations for
the cells from the internal cell library.
``tests/``
This directory contains the suite of unit tests and regression tests used by
Docs: Update build_verific Clarify partially supported builds section. Update parameter defaults. Include note on finding compile options with `yosys-config`. Fix remaining references to `/yosys_source/`.
2024-08-21 17:03:59 -05:00
Yosys. See :doc:`/yosys_internals/extending_yosys/test_suites`.
Reorganising documentation Also changing to furo theme.
2023-08-02 16:20:29 -05:00
Docs: tidying - Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width.
2024-01-29 18:31:00 -06:00
The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`,
:file:`passes/{*}/Makefile.inc` and :file:`backends/{*}/Makefile.inc`. So when
extending Yosys it is enough to create a new directory in :file:`frontends/`,
:file:`passes/` or :file:`backends/` with your sources and a
:file:`Makefile.inc`. The Yosys kernel automatically detects all commands linked
with Yosys. So it is not needed to add additional commands to a central list of
commands.
Reorganising documentation Also changing to furo theme.
2023-08-02 16:20:29 -05:00
Good starting points for reading example source code to learn how to write
Docs: tidying - Use `:file:` role for file names, as well as `:makevar:` and `:program:`. - Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets. - Add link to ABC. - More (and better) links to code examples. Formatted `:file:` text with link to source on github. - Includes a few extra todos (mostly picking up inline code blocks and a couple intro reminders). - Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags. - Reflowing some paragraphs for spacing/width.
2024-01-29 18:31:00 -06:00
passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
Reorganising documentation Also changing to furo theme.
2023-08-02 16:20:29 -05:00
See the top-level README file for a quick Getting Started guide and build
instructions. The Yosys build is based solely on Makefiles.
Users of the Qt Creator IDE can generate a QT Creator project file using make
qtcreator. Users of the Eclipse IDE can use the "Makefile Project with Existing
Code" project type in the Eclipse "New Project" dialog (only available after the
CDT plugin has been installed) to create an Eclipse project in order to
programming extensions to Yosys or just browse the Yosys code base.