Electronic System Design Group
Settings¶
The script uses settings using a YAML file passed using the --settings
argument (see Arguments).
The description of the YAML file is described here.
python ./projectflow.py --settings <SETTINGS.YML>
Sections¶
<CATEGORY>:
¶
The category of the project from list of categories: in the configuration file (see Configuration). Ths defines the repository layout of the project (see <CATEGORY>_layout:).
name:
¶
Name of the project.
Note
The value here is used by Tag Substitution replacing the <NAME>
tags in the
Configuration file.
contrib_lib:
¶
Name of the contributor’s library. This defines the owner of the project and is used in the path to the location/structure of the project as it is stored in the externally hosted repository.
Note
contributors: defines a list of all of the contributors. The value here is used by
Tag Substitution replacing <CONTRIB_LIB>
tags in the Configuration file.
top_level:
¶
Name of the top-level entity HDL
component. This can be a str
or list
and the entity name should
appear in the HDL
filename. If no top-levels are supplied the script will search for files in library
(determined from name:) for filenames which contain name: and one term from:
['top_', '_top']
. If none are found the script will exit.
Used by projectflow
in conjunction with board_id: to generate the
FPGA Vendor project name, if no board_id: is supplied:
<TOP_LEVEL>
where <TOP_LEVEL>
is the first item in top_level: list (or the str of
top_level: is supplied as a single entry).
The project name can be overwritten by project_name_override:
top_level_tb_entity:
¶
Name of the top-level test-bench used when executing VUnit
simulations.
vendor:
¶
Name of the FPGA vendor the project is targeting.
Note
The value here is used by Tag Substitution replacing <VENDOR>
tags in the
Configuration file.
family:
¶
Name of the FPGA family the project is targeting.
Note
The value here is used by Tag Substitution replacing <FAMILY>
tags in the
Configuration file.
tool_version:
¶
Version of the FPGA vendor tool to use for the generation of the project.
Note
The value here is used by Tag Substitution replacing <TOOL_VERSION>
tags in the
Configuration file.
tool_mode:
¶
Value to set the corresponding system environment variable to define the FPGA vendor tool operating mode. Sets either 32 or 64 bit operation.
device:
¶
FPGA vendor defined device identifier to use for the generation of the project.
board_id:
¶
A hex represented 32 bit number to insert into the FPGA project via a top-level generic named:
g_board_id
. This will be converted into a integer.
set_parameter -name g_board_id 0
generic(
g_board_id : integer := 0
);
This can then be used in user logic using:
constant c_board_id : std_logic_vector(31 downto 0) := std_logic_vector(to_unsigned(g_board_id, 32));
Note
This is a board only option.
board_timestamp_enabled:
¶
The script will generate a Unix 32 bit timestamp for when the corresponding FPGA project is generated by the
script. If this option is enabled using True
the timestamp will be inserted via a top-level generic
named: g_board_timestamp
.
set_parameter -name g_board_timestamp 0
generic(
g_board_timestamp : integer := 0
);
This can then be used in user logic using:
constant c_board_timestamp : std_logic_vector(31 downto 0) := std_logic_vector(to_unsigned(g_board_timestamp, 32));
Note
This is a board only option.
board:
¶
Predefined hardware to target when generating the project. If supplied projectflow
will use this value
to generate the FPGA Vendor project name in the form:
<BOARD>_<TOP_LEVEL>
where <BOARD>
is the board_id: name and <TOP_LEVEL>
is the first item in
top_level: list (or the str of top_level: is supplied as a single entry).
The project name can be overwritten by project_name_override:
board_settings:
¶
Name of the settings file to parse when associating board
with design.
Warning
Options in this file will overwrite options in the calling settings file.
project_name_override:
¶
Option to override the automatically generated project name with a custom name.
sim_vendor:
¶
Simulation vendor to use when running simulations.
sim_version:
¶
Version of the simulation tool to use when running simulations.
Note
The value here is used by Tag Substitution replacing <SIM_VERSION>
in the
Configuration file.
sim_mode:
¶
Value to set the corresponding system environment variable to define the simulation tool operating mode. Sets either 32 or 64 bit operation.
sim_init_script:
¶
Name of the simulation initialisation script to usw when running simulations in GUI mode.
Note
Use: $env(REPO_ROOT)
to avoid including user specific absolute paths in this file.
use_glbl:
¶
If True
adds glbl dependencies to xilinx
simulations.
Note
This is a xilinx
only option and is ignored for altera
projects.
vunit_args:
¶
Allows options from settings.yml
YAML file to be passed to VUnit
as if they are command-line
arguments. For detailed information see: VUnit Documentation.
vunit_args:
version: False
list: False
files: False
log_level: warning
output_path: simulation/vunit_output
test_patterns:
- None
keep_compiling: True
num_threads: 2
elaborate: False
verbose: False
xunit_xml: xunit_report.xml
coverage:
unique_sim: False
exit_0: False
no_color: False
quiet: True
xunit_xml_format: 'bamboo'
dont_catch_exceptions: False
export_json: ''
with_attributes:
without_attributes:
compile: False
fail_fast: False
version:
¶
Reports the version being used. See: vunit_cli
Warning
If True
This will report the version number and exit, not running VUnit
. The script will raise a
warning log if this option is set.
list:
¶
Lists the test-cases being used without executing the simulation. See: vunit_cli
Warning
If True
This will list the test-cases being used by simulation and exit, not running VUnit
.
The script will raise a warning log if this option is set.
files:
¶
Lists the HDL files being used without executing the simulation. See: vunit_cli
Warning
If True
This will list the files being used by simulation and exit, not running VUnit
.
The script will raise a warning log if this option is set.
test_patterns:
¶
List of test-cases or test-case patterns to simulate. - None
will not run any test-cases.
keep_compiling:
¶
If True
keep compiling HDL if errors are found. Otherwise will exit on first error. See: vunit_cli
xunit_xml_format:
¶
Sets the format for the generated xunit_xml
report file. Set to 'bamboo'
. See: vunit_cli
dont_catch_exceptions:
¶
- From VUnit Documentation: “Let exceptions bubble up all the way. Useful when running with “python -m pdb”.”.
- See: vunit_cli
export_json:
¶
From VUnit Documentation: “Export project information to a JSON file.”
json
file will be generated in the output_path:
. Leave blank to skip generation. See: vunit_cli
with_attributes:
¶
List of test-cases or test-case to simulate which do have these attributes. Leave blank or have a
single item of ''
to ignore.
From VUnit Documentation: “Only select tests with these attributes set”
repository_config:
¶
Defines location in externally hosted source-code repository for the top-level project and each dependency
required to execute projectmanager
git:
¶
repository_config:
git:
<NAME>:
enabled: True
vunit_default: False
url: <https://<GIT_BITBUCKET_URL/>
path: tools/xml2vhdl
branch: master
tag:
required_vhdl_libs: []
Warning
Tag Substitution has not been tested here. <>
Should be replaced by actual values.
<NAME>:
¶
The name of the project or project dependency.
enabled:
- Location is processed by the script if set to:
True
, otherwise skipped if set to:False
. vunit_default:
- Location is processed by Vunit` if set to:
True
, otherwise skipped byVunit
if set to:False
. url:
Top-Level URL of externally hosted
git
repository hosted onbitbucket
.Note
This is the
clone
URL frombitbucket
with theusername@
portion removed.username@
will be generated byprojectmanager
from$BITBUCKET_USERNAME
system environment variable.path:
- Path of location on the local file-system. Should match project path based on categories: and <CATEGORY>_layout: for the project or project dependency being defined.
branch:
- Specific
git
branch
to use. tag:
Specific
git
tag
to use.Note
tag:
is not used in the context of usingFPGAFlow
to clone git repositories. The user is expected to managetags
andbranches
for development purposes after the repository has been cloned.required_vhdl_libs:
List of required VHDL libraries, names matching corresponding
<NAME>
entry in git: or subversion:.Note
required_vhdl_libs:
is currently only used to ensure the VHDL libraries used byXML2VHDL
script are included and enabled inprojectflow
.
subversion:
¶
repository_config:
subversion:
<NAME>:
enabled: True
vunit_default: True
url: <https://<SVN_REPO_ROOT_URL/>
path: <CATEGORY>/<CONTRIB_LIB>/<NAME>
subpath: trunk
rev: HEAD
required_vhdl_libs: []
Warning
Tag Substitution has not been tested here. <>
Should be replaced by actual values.
<NAME>:
¶
The name of the project or project dependency.
enabled:
- Location is processed by the script if set to:
True
, otherwise skipped if set to:False
. vunit_default:
- Location is processed by Vunit` if set to:
True
, otherwise skipped byVunit
if set to:False
. url:
- Top-Level URL of externally hosted
SVN
repository. path:
- Path of location in repository. Should match project path based on categories: and <CATEGORY>_layout: for the project or project dependency being defined.
subpath:
'trunk'
,'branches/<BRANCH_NAME>'
or'tag/<TAG_NAME>'
for the project or project dependency being defined.rev:
- Specific
SVN
revision orHEAD
. required_vhdl_libs:
- List of required VHDL libraries, names matching corresponding
<NAME>
entry in git: or subversion:.
documentation:
¶
documentation:
project_title: 'Project Documentation Title'
project_version: '2019.1'
project_author: 'Electronic System Design Group, Technology'
project_org: 'Science and Technology Facilities Council'
project_release:
doxy_version: 1.8.14
dot_version: 2.40.1
sphinx_version: 1.8.2
image_path: common/images
logo_path: common/logo
logo_name: logo.png
source_path: common/source
language: vhdl
restricted_src: False
doc_clean: True
release_uri: 'https://bitbucket.org/mjroberts/fpgaflow/branch/release'
issue_uri: False
releases_document_name: False
doxy_mainpage:
name: 'README.md'
autogen_pagelinks: True
autostruct:
- 'readme_header.md'
- 'readme_description.md'
project_title:
¶
The Name of the Current Project Documentation.
project_author:
¶
The Project Documentation Author.
project_org:
¶
The Project Documentation Organisation.
project_release:
¶
The Project Documentation Release Tag.
doxy_version:
¶
The Version of doxygen
to use to build VHDL
documentation.
Note
This version should be available on the host system and this value must be included in the documentation: doxygen: support_tools: within the configuration file (see Configuration).
dot_version:
¶
The Version of graphviz
used by doxygen
when building documentation.
Note
This version should be available on the host system and this value must be included in the documentation: dot: support_tools: within the configuration file (see Configuration).
sphinx_version:
¶
The Version of sphinx
used when building documentation.
Note
This version should be available on the host system, either globally installed or included in the python virtual environment (see Python Modules) and this value must be included in the documentation: sphinx: support_tools: within the configuration file (see Configuration).
image_path:
¶
The path of the image directory to include in the generated documentation. This path is relative to: ./docs
logo_path:
¶
The path of the logo directory to include in the generated documentation. This path is relative to: ./docs
logo_name:
¶
The name of the logo file, which must exist in the logo_path: to use in the generated documentation.
source_path:
¶
The path additional source directory to include in the generated documentation. This path is relative to:
./docs
language:
¶
The main language used in the project.
python
- Documentation will be generated using
sphinx
only. vhdl
Documentation will be generated using
doxygen
fromVHDL
source code. This will then be included and referenced bysphinx
which provides the top-level documentation for the project.Note
This language must be included in the documentation: supported_languages: within the configuration file (see Configuration).
restricted_src:
¶
When this option is set True
doxygen
is prevented from including source code in the generated
documentation. Valid values are: True
or False
.
Note
restricted_src:
defaults to True
if the option is not included in the settings file.
doc_clean:
¶
When this option is set True
the documentation build paths are deleted prior to building the project
documentation. Valid values are: True
or False
.
release_uri:
¶
Using releases to handle changelogs. See releases_usage. This is currently configured for
bitbucket
so /%s
is appended to the end of the supplied URL automatically.
Note
release_uri:
is optional, if not used it should be set to False
in the settings file.
issue_uri:
¶
Using releases to handle changelogs. See releases_usage.
Note
issue_uri:
is optional, if not used it should be set to False
in the settings file.
releases_document_name:
¶
Using releases to handle changelogs. See releases_usage. If not defined here it will
default to changelog.rst
.
Note
releases_document_name:
is optional, if not used it should be set to False
in the settings file.
doxy_mainpage:
¶
These options define the doxygen
mainpage used to reference any pages generated by doxygen
from source
code, which is then referenced by the top-level documentation generated by sphinx
.
name:
- Name of the mainpage to generate.
autostruct:
- A list of files, which should be placed in the projects docs/doxygen/source directory, which should be
added to the mainpage used by
doxygen
. The order of the list defines the order the contents of these files will by added to the mainpage. autogen_pagelinks:
Configures if the documentation generated by
doxygen
should be parsed to (re)generate links to pages to include on the mainpage. Valid values are:True
orFalse
.This will automatically generate a file named:
<lowercase_name>_links.md
where<lowercase_name>
matches the name of the mainpage to generate defined byname:
.Note
When generating documentation
doxygen
uses either the@page uniquename
or\page uniquename
tags to define the name of the generated page. By using the convention of suffixingpage
to theuniquename
so that it becomes:uniquenamepage
it is possible for thedocflow.py
script to automatically add these pages as a list of links on mainpage generated bydoxygen
.This option will cause
doxygen
to generate documentation twice, once to generate the pages, the second time to reference the pages on it’s mainpage.