TCL: write_project_tcl description

REF

tclapp/xilinx/projutils/doc/write_project_tcl

Description:

Create a Tcl script to re-create the current project. The generated script will contain the Tcl commands for creating the project, setting the project type, creating filesets, adding/importing source files, and defining runs and run properties. The re-created project will be functionally equivalent to the original project.

This generated Tcl project script and the various design sources can be stored in a version control system for source file management and project archival.

To re-create the project, you should source the generated Tcl script in a Vivado Tcl shell from the same directory where the script was generated. If the original project already exists in the same project directory, the script may fail with an error message that the project already exists. In this case you may want to run the script from a different directory path or update the generated script by adding a “-force” switch to the “create_project” command.

In the generated Tcl script, the project source files are referenced relative to the “origin_dir” variable. By default, the source files are referenced relative to the directory where the tcl script is generated. The “origin_dir” is set to “.” (the current tcl script directory). When the script is executed from this directory, any source files will be referenced relative to this ‘origin_dir’ path value.

In the case where the script is sourced from a different directory or physically moved to a different directory, then the “origin_dir” variable MUST be manually set relative to the new directory. Manually set the “origin_dir” to make sure that the source files are correctly referenced relative to the original location.

You can have the “origin_dir” automatically set to a directory of your choice by using the -paths_relative_to option. All the source file paths will be defined relative to the directory specified with this option.

If -absolute_path is specified, the project source files will be referenced using absolute paths only. In this case, the script can be executed from any directory provided these absolute paths are accessible in the same filesystem.

If the original project contains IP cores, the following rules apply in the generated script while re-creating the project:-

1. The IP will not be regenerated, if it was generated in the original project.
   
   In this case, the script will “add” the IP from the original project with generated synthesis/simulation products.

2. The IP will be generated, if it was not generated in the original project.

In this case, the script will “add” the IP from the original project and create OOC synthesis runs for generating the synthesis/simulation products.

If the original project had completed runs, those runs will be re-created with the same settings in the generated project; however those runs will not be automatically launched in order to save runtime.

Arguments:

-paths_relative_to - (Optional) Specify the directory path relative to which the sources will referenced when re-creating the project. The path will be set for the “origin_dir” variable in the generated script.

-target_proj_dir - (Optional) Specify the directory path where the project will be recreated. The tool will write “create_project” command with the directory path specified with this switch.

-force - (Optional) Overwrite an existing project script file of the same name. If the script file already exists, the tool returns an error unless the -force argument is specified.

-all_properties - (Optional) Write all properties (default and non-default) for the project. The tool will write “set_property” commands for setting the properties for objects like project, filesets, files, runs etc.

Note: By default, if the -all_properties switch is not specified, then only the non-default properties will be written to the script.

-no_copy_sources - (Optional) Do not import sources even if they are local to the original project. The tool will not import the files that were local in the original project into the new project. If the design contains BD sources then -use_bd_files switch must also be provided.

-no_ip_version - (Optional) Flag to not include the IP version as part of the IP VLNV in create_bd_cell commands. NOTE - this may have implications if there are major IP version changes.

-absolute_path - (Optional) Make all file paths absolute in the generated script. This allows running the script from any location in that filesystem. By default the file paths will be relative to the origin_dir variable.

-dump_project_info - (Optional) Dump information about all properties to two text files, <project_name>_dump.txt (short), and <project_name>_def_val.txt (detailed).

-use_bd_files - (Optional) Use block design sources directly instead of writing out procs to create them. If the -no_copy_sources switch is provided the BD files will be added (but not copied locally) to the project. Otherwise the files will be imported (copied locally) to the project.

-internal - (Optional) Print only basic header information in the generated tcl script. By default information about required file sources will also be part of the header.

-quiet - (Optional) Execute the command quietly, returning only ERROR messages.

-verbose - (Optional) Temporarily override any message limits and return all messages from this command.

Note: Message limits can be defined with the set_msg_config command.

- (Required) The name of the output Tcl script file to be created by the write_project_tcl command. The tool will apply an extension of ‘.tcl’ if a file extension is not supplied.

Examples:

Example 1

The following example exports a Tcl script named “recreate.tcl” for the test project:-

Start Vivado in tcl mode and execute following commands:
% open_project test/test.xpr
% write_project_tcl recreate.tcl
% close_project

Example 2

The following example exports a Tcl script named “recreate.tcl” for the test project in the “./script” directory and specifies the “/tmp/test” directory path in the “create_project” command. When the “recreate.tcl” script is sourced in the Vivado Tcl shell, the project will be re-created in “/tmp/test” directory:-

Start Vivado in tcl mode and execute following commands:
% open_project test/test.xpr
% write_project_tcl -target_proj_dir “/tmp/test” ./script/recreate.tcl
% close_project
% source script/recreate.tcl

Example 3

The following Tcl commands exports Tcl script for the current project and writes all the properties, both default or non-default values:-

% write_project_tcl -all_properties recreate.tcl

Example 4

The following Tcl commands exports Tcl script for the current project and adds files that are local in this project. The recreated project will reference these files:-

% write_project_tcl -no_copy_sources recreate.tcl

Example 5

The following Tcl and shell commands opens a test project, exports “recreate.tcl” script for the current project in the current working directory, creates a new project in ./my_test directory, prints the list of files in the new project, prints the current project settings and then closes the newly created project:-

Start Vivado in tcl mode and execute following commands:
% open_project test/test.xpr
% write_project_tcl -force recreate.tcl
% close_project
% exit

From OS shell:

mkdir my_test
cd my_test
vivado -mode batch -source ../recreate.tcl -tclargs --origin_dir ..

Start Vivado in tcl mode and execute following commands:
% open_project test/test.xpr
% get_files -of_objects [get_filesets sources_1]
% report_property [current_project]
% close_project

Example 6

The following Tcl commands creates a new project named bft_test, adds files to the project, sets the fileset property, exports a tcl script named “bft.tcl” in the current working directory, creates a new project in “./my_bft” directory, prints the list of files in the new project (test_1.v and test_2.v), prints the “verilog_define” property value and then closes the newly created project:-

Start Vivado in tcl mode and execute following commands:
% create_project bft_test ./bft_test
% add_files test_1.v
% add_files test_2.v
% set_property verilog_define {a=10} [get_filesets sources_1]
% write_project_tcl -force bft.tcl
% close_project
% exit

From OS shell:

mkdir my_bft
cd my_bft
vivado -mode batch -source ../bft.tcl -tclargs --origin_dir ..

Start Vivado in tcl mode and execute following commands:
% open_project bft_test/bft_test.xpr
% get_files -of_objects [get_filesets sources_1]
% get_property verilog_define [get_filesets sources_1]
% close_project

See Also:

• add_files
• archive_project
• close_project
• create_project
• current_project
• get_files
• get_property
• open_project
• report_property
• set_property