write_project_tcl - 2024.1 English

Vivado Design Suite Tcl Command Reference Guide (UG835)

Document ID
UG835
Release Date
2024-05-30
Version
2024.1 English

(User-written application) Export Tcl script for re-creating the current project

Syntax

write_project_tcl [‑paths_relative_to <arg>] [‑origin_dir_override <arg>]
    [‑target_proj_dir <arg>] [‑force] [‑all_properties] [‑no_copy_sources]
    [‑absolute_remote_path] [‑no_ip_version] [‑absolute_path]
    [‑dump_project_info] [‑use_bd_files] [‑no_bd_xlnoc] [‑internal]
    [‑validate] [‑ignore_msg_control_rules] [‑quiet] [‑verbose] <file>

Returns

True (0) if success, false (1) otherwise.

Usage

Name Description
[-paths_relative_to] Override the reference directory variable for source file relative paths Default: Script output directory path
[-origin_dir_override] Set 'origin_dir' directory variable to the specified value (Default is value specified with the -paths_relative_to switch) Default: None
[-target_proj_dir] Directory where the project needs to be restored Default: Current project directory path
[-force] Overwrite existing tcl script file
[-all_properties] Write all properties (default & non-default) for the project object(s)
[-no_copy_sources] Do not import sources even if they were local in the original project Default: 1
[-absolute_remote_path] Write remote sources with absolute paths
[-no_ip_version] Flag to not include the IP version as part of the IP VLNV in create_bd_cell commands. Default: 1
[-absolute_path] Make all file paths absolute wrt the original project directory
[-dump_project_info] Write object values
[-use_bd_files] Use BD sources directly instead of writing out procs to create them
[-no_bd_xlnoc] Do not create BD xlnoc cell Default: 1
[-internal] Print basic header information in the generated tcl script
[-validate] Runs a validate script before recreating the project. To test if the files and paths refrenced in the tcl file exists or not.
[-ignore_msg_control_rules] Do not imports message control rules in tcl script
[-quiet] Execute the command quietly, returning no messages from the command.
[-verbose] Suspend message limits during command execution
<file> Name of the tcl script file to generate

Description

Creates a Tcl script to recreate 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, defining runs and run properties.

Important: The new project will be created in the current working directory (CWD) where the generated Tcl script is sourced from. The script written out by write_project_tcl should be sourced in the same directory from which it was created. If you source the script from a different directory, you should first set the <origin_dir_loc> variable in Tcl shell to this alternate directory, or edit the script to define the <origin_dir> variable in the script in order to maintain the relative path between the CWD and the source files referenced in the script.

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

Arguments

-paths_relative_to <arg> - (Optional) Change the 'origin_dir' variable for the relative paths of source files.

-origin_dir_override <arg> - (Optional) Override the 'origin_dir' directory variable to the specified value. The default is the value specified with the -paths_relative_to option.

-target_proj_dir <arg> - (Optional) Specify the directory path where the project will be recreated. The tool will write the create_project command using the directory path specified with this option. The default is the current project directory.

-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 all the objects like project, filesets, files, runs etc.

Tip: By default, if the -all_properties switch is not specified, only 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.

Important: This option requires the addition of the -use_bd_files switch for designs that contain block diagrams.

-absolute_path - (Optional) Make all file paths absolute with regard to the original project directory.

-dump_project_info - (Optional) Writes a file containing a dump of the current values of all objects in the design, and well as a file indicating what the default values are for all objects in the design. These files can be used to aide in debugging issues with the recreated project.

-use_bd_files - (Optional) Use block diagram sources (.bd) from the Vivado™ IP integrator directly instead of writing out Tcl scripts to recreate them. By default the write_project_tcl command will recreate the block diagram as a Tcl proc inside the project Tcl script. With the use of the -use_bd_files option, the block design sources will be copied or referenced like all other design sources according to the -no_copy_sources option.

-internal - (Optional) Includes basic header information in the generated Tcl script.

-quiet - (Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution.
Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.
-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.

<file> - (Required) The name of the 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

The following example exports Tcl script named recreate.tcl for the current project:

write_project_tcl recreate.tcl

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

write_project_tcl -target_proj_dir "/tmp/test" ./script/recreate.tcl

The following command 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

The following command 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 -use_bd_files recreate.tcl
Important: The -use_bd_files switch is required for use with -no_copy_sources in designs with block diagrams.

The following command 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:

open_project ./test/test.xpr
write_project_tcl -force recreate.tcl
close_project
file mkdir my_test
cd my_test
source ../recreate.tcl
get_files -of_objects [get_filesets sources_1]
report_property [current_project]
close_project

The following command 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:

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
file mkdir my_bft
cd my_bft
source ../bft.tcl
get_files -of_objects [get_filesets sources_1]
get_property verilog_define [get_filesets sources_1]
close_project