mirrors/yosys
3
0
Fork 0
mirror of https://github.com/YosysHQ/yosys synced 2025-04-04 08:39:58 +00:00
Code Activity

Moving primary build instructions to docs

Browse source 
Also drop visual studio instructions.
This commit is contained in:
Krystine Sherwin 2024-12-05 09:21:13 +13:00
parent 2bd53395fe
commit 0aef78245e
No known key found for this signature in database
2 changed files with 131 additions and 139 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

142
README.md
View file

@ -18,6 +18,7 @@ Third-party software distributed alongside this software
is licensed under compatible licenses. is licensed under compatible licenses.
Please refer to `abc` and `libs` subdirectories for their license terms. Please refer to `abc` and `libs` subdirectories for their license terms.
Web Site and Other Resources Web Site and Other Resources
============================ ============================
@ -49,9 +50,25 @@ For more information about the difference between Tabby CAD Suite and the OSS CA
Many Linux distributions also provide Yosys binaries, some more up to date than others. Check with your package manager! Many Linux distributions also provide Yosys binaries, some more up to date than others. Check with your package manager!
Building from Source Building from Source
==================== ====================
For more details, and instructions for other platforms, check [building from
source](https://yosyshq.readthedocs.io/projects/yosys/en/latest/getting_started/installation.html#building-from-source)
on Read the Docs.
When cloning Yosys, some required libraries are included as git submodules. Make
sure to call e.g.
$ git clone --recurse-submodules https://github.com/YosysHQ/yosys.git
or
$ git clone https://github.com/YosysHQ/yosys.git
$ cd yosys
$ git submodule update --init --recursive
You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is You need a C++ compiler with C++17 support (up-to-date CLANG or GCC is
recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make. recommended) and some standard tools such as GNU Flex, GNU Bison, and GNU Make.
TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile). TCL, readline and libffi are optional (see ``ENABLE_*`` settings in Makefile).
@ -65,58 +82,22 @@ prerequisites for building yosys:
graphviz xdot pkg-config python3 libboost-system-dev \ graphviz xdot pkg-config python3 libboost-system-dev \
libboost-python-dev libboost-filesystem-dev zlib1g-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev
Similarily, on Mac OS X Homebrew can be used to install dependencies (from within cloned yosys repository):
$ brew tap Homebrew/bundle && brew bundle
or MacPorts:
$ sudo port install bison flex readline gawk libffi \
git graphviz pkgconfig python36 boost zlib tcl
On FreeBSD use the following command to install all prerequisites:
# pkg install bison flex readline gawk libffi\
git graphviz pkgconf python3 python36 tcl-wrapper boost-libs
On FreeBSD system use gmake instead of make. To run tests use:
% MAKE=gmake CC=cc gmake test
For Cygwin use the following command to install all prerequisites, or select these additional packages:
setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,boost-build,zlib-devel
The environment variable `CXX` can be used to control the C++ compiler used, or The environment variable `CXX` can be used to control the C++ compiler used, or
run one of the following: run one of the following to override it:
$ make config-clang $ make config-clang
$ make config-gcc $ make config-gcc
Note that these will result in `make` ignoring the `CXX` environment variable, The Makefile has many variables influencing the build process. These can be
unless `CXX` is assigned in the call to make, e.g. adjusted by modifying the Makefile.conf file which is created at the `make
config-...` step (see above), or they can be set by passing an option to the
make command directly:
$ make CXX=$CXX $ make CXX=$CXX
The Makefile has many variables influencing the build process. These can be For other compilers and build configurations it might be necessary to make some
adjusted by modifying the Makefile.conf file which is created at the changes to the config section of the Makefile. It's also an alternative way to
`make config-...` step (see above), or they can be set by passing an option set the make variables mentioned above.
to the make command directly.
For example, if you have clang, and (a compatible version of) `ld.lld`
available in PATH, it's recommended to speed up incremental builds with
lld by enabling LTO:
$ make ENABLE_LTO=1
On macOS, LTO requires using clang from homebrew which isn't in PATH
rather than xcode clang.
$ make ENABLE_LTO=1 CXX=$(brew --prefix)/opt/llvm/bin/clang++
For other compilers and build configurations it might be
necessary to make some changes to the config section of the
Makefile. It's also an alternative way to set the make variables
mentioned above.
$ vi Makefile # ..or.. $ vi Makefile # ..or..
$ vi Makefile.conf $ vi Makefile.conf
@ -126,10 +107,9 @@ To build Yosys simply type 'make' in this directory.
$ make $ make
$ sudo make install $ sudo make install
Note that this also downloads, builds and installs ABC (using yosys-abc Tests are located in the tests subdirectory and can be executed using the test
as executable name). target. Note that you need gawk as well as a recent version of iverilog (i.e.
build from git). Then, execute tests via:
Tests are located in the tests subdirectory and can be executed using the test target. Note that you need gawk as well as a recent version of iverilog (i.e. build from git). Then, execute tests via:
$ make test $ make test
@ -140,6 +120,7 @@ To use a separate (out-of-tree) build directory, provide a path to the Makefile.
Out-of-tree builds require a clean source tree. Out-of-tree builds require a clean source tree.
Getting Started Getting Started
=============== ===============
@ -289,68 +270,3 @@ From the root of the repository, run `make docs`. This will build/rebuild yosys
as necessary before generating the website documentation from the yosys help as necessary before generating the website documentation from the yosys help
commands. To build for pdf instead of html, call commands. To build for pdf instead of html, call
`make docs DOC_TARGET=latexpdf`. `make docs DOC_TARGET=latexpdf`.
Building for Windows
====================
Creating the Visual Studio Template Project
-------------------------------------------
1. Create an empty Visual C++ Win32 Console App project
Microsoft Visual Studio Express 2013 for Windows Desktop
Open New Project Wizard (File -> New Project..)
Project Name: YosysVS
Solution Name: YosysVS
[X] Create directory for solution
[ ] Add to source control
[X] Console applications
[X] Empty Project
[ ] SDL checks
2. Open YosysVS Project Properties
Select Configuration: All Configurations
C/C++ -> General -> Additional Include Directories
Add: ..\yosys
C/C++ -> Preprocessor -> Preprocessor Definitions
Add: _YOSYS_;_CRT_SECURE_NO_WARNINGS
3. Resulting file system tree:
YosysVS/
YosysVS/YosysVS
YosysVS/YosysVS/YosysVS.vcxproj
YosysVS/YosysVS/YosysVS.vcxproj.filters
YosysVS/YosysVS.sdf
YosysVS/YosysVS.sln
YosysVS/YosysVS.v12.suo
4. Zip YosysVS as YosysVS-Tpl-v1.zip
Compiling with Visual Studio
----------------------------
Visual Studio builds are not directly supported by build scripts, but they are still possible.
1. Easy way
- Go to https://github.com/YosysHQ/yosys/actions/workflows/vs.yml?query=branch%3Amain
- Click on the most recent completed run
- In Artifacts region find vcxsrc and click on it to download
- Unpack downloaded ZIP file
- Open YosysVS.sln with Visual Studio
2. Using WSL or MSYS2
- Make sure to have make, python3 and git available
- Git clone yosys repository
- Execute ```make vcxsrc YOSYS_VER=latest```
- File yosys-win32-vcxsrc-latest.zip will be created
- Transfer that file to location visible by Windows application
- Unpack ZIP
- Open YosysVS.sln with Visual Studio

128
docs/source/getting_started/installation.rst
View file

@ -62,9 +62,21 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
Building from source Building from source
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
Refer to the `readme`_ for the most up-to-date install instructions. .. TODO:: discuss release packages (and figure out what is/isn't included)
.. _readme: https://github.com/YosysHQ/yosys#building-from-source The Yosys source files can be obtained from the `YosysHQ/Yosys git repository`_.
`ABC`_ and some of the other libraries used are included as git submodules. To
clone these submodules at the same time, use e.g.:
.. code:: console
git clone --recurse-submodules https://github.com/YosysHQ/yosys.git # ..or..
git clone https://github.com/YosysHQ/yosys.git
cd yosys
git submodule update --init --recursive
.. _YosysHQ/Yosys git repository: https://github.com/yosyshq/yosys/
.. _ABC: https://github.com/berkeley-abc/abc
Supported platforms Supported platforms
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
@ -90,21 +102,99 @@ libffi, Tcl and zlib; are optional but enabled by default (see
:makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the :makevar:`ENABLE_*` settings in Makefile). Graphviz and Xdot are used by the
`show` command to display schematics. `show` command to display schematics.
.. TODO:: check there aren't any extra prereqs that are already installed on git images
Installing all prerequisites for Ubuntu 20.04: Installing all prerequisites for Ubuntu 20.04:
.. code:: console .. code:: console
sudo sudo apt-get install build-essential clang lld bison flex \ sudo apt-get install gperf build-essential bison flex \
libreadline-dev gawk tcl-dev libffi-dev git make \ libreadline-dev gawk tcl-dev libffi-dev git graphviz \
graphviz xdot pkg-config python3 libboost-system-dev \ xdot pkg-config python3 libboost-system-dev \
libboost-python-dev libboost-filesystem-dev zlib1g-dev libboost-python-dev libboost-filesystem-dev zlib1g-dev
Installing all prerequisites for macOS 11 (with Homebrew): Installing all prerequisites for macOS 13 (with Homebrew):
.. code:: console .. code:: console
brew install bison flex gawk libffi git graphviz \ brew tap Homebrew/bundle && brew bundle
pkg-config python3 tcl-tk xdot bash boost-python3
.. TODO:: check these are still up to date
or MacPorts:
.. code:: console
sudo port install bison flex readline gawk libffi graphviz \
pkgconfig python36 boost zlib tcl
.. todo:: Is there a console alternative that has the # prefix instead of $?
On FreeBSD use the following command to install all prerequisites:
.. code:: console
pkg install bison flex readline gawk libffi graphviz \
pkgconf python3 python36 tcl-wrapper boost-libs
.. note:: On FreeBSD system use gmake instead of make. To run tests use:
``MAKE=gmake CC=cc gmake test``
For Cygwin use the following command to install all prerequisites, or select these additional packages:
.. code::
setup-x86_64.exe -q --packages=bison,flex,gcc-core,gcc-g++,git,libffi-devel,libreadline-devel,make,pkg-config,python3,tcl-devel,boost-build,zlib-devel
Build configuration
^^^^^^^^^^^^^^^^^^^
The Yosys build is based solely on Makefiles, and uses a number of variables
which influence the build process. The recommended method for configuring
builds is with a ``Makefile.conf`` file in the root ``yosys`` directory. The
following commands will clean the directory and provide an initial configuration
file:
.. code:: console
make config-clang # ..or..
make config-gcc
Check the root Makefile to see what other configuration targets are available.
Other variables can then be added to the ``Makefile.conf`` as needed, for
example:
.. code:: console
echo "ENABLE_ZLIB := 0" >> Makefile.conf
Using one of these targets will set the ``CONFIG`` variable to something other
than ``none``, and will override the environment variable for ``CXX``. To use a
different compiler than the default when building, use:
.. code:: console
make CXX=$CXX # ..or..
make CXX="g++-11"
.. note::
Setting the compiler in this way will prevent some other options such as
``ENABLE_CCACHE`` from working as expected.
If you have clang, and (a compatible version of) ``ld.lld`` available in PATH,
it's recommended to speed up incremental builds with lld by enabling LTO with
``ENABLE_LTO=1``. On macOS, LTO requires using clang from homebrew rather than
clang from xcode. For example:
.. code:: console
make ENABLE_LTO=1 CXX=$(brew --prefix)/opt/llvm/bin/clang++
By default, building (and installing) yosys will build (and install) `ABC`_,
using :program:`yosys-abc` as the executable name. To use an existing ABC
executable instead, set the ``ABCEXTERNAL`` make variable to point to the
desired executable.
Running the build system Running the build system
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
@ -116,25 +206,14 @@ From the root ``yosys`` directory, call the following commands:
make make
sudo make install sudo make install
This will build and then install Yosys, making it available on the command line To use a separate (out-of-tree) build directory, provide a path to the Makefile.
as ``yosys``. Note that this also downloads, builds, and installs `ABC`_ (using
:program:`yosys-abc` as the executable name).
.. _ABC: https://github.com/berkeley-abc/abc
The default compiler is ``clang``, to change between ``clang`` and ``gcc``, use
one of the following:
.. code:: console .. code:: console
make config-clang mkdir build; cd build
make config-gcc make -f ../Makefile
To use a compiler different than the default, use: Out-of-tree builds require a clean source tree.
.. code:: console
make CXX="g++-11"
.. seealso:: .. seealso::
@ -202,9 +281,6 @@ commands.
Good starting points for reading example source code to learn how to write Good starting points for reading example source code to learn how to write
passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`. passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
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 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 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 Code" project type in the Eclipse "New Project" dialog (only available after the