Quartus® II Tcl Example: Opening Projects

author-image

By

Almost every Quartus II Tcl script opens a project. There are a number of approaches for opening projects, and this page includes code samples for opening projects.

It is useful to write scripts so that project and revision names are passed to the script at run-time, as command-line arguments. This makes it easy to reuse scripts with different projects. The cmdline Tcl package, included with the Quartus II software, makes it easy to pass command-line arguments to scripts.

Here is an example of code that opens a project with the project and revision names you specify as command-line arguments.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

project_open $opts(project) -revision $opts(revision)

At a DOS or shell prompt, you can run a script that contains that code as shown here:

quartus_sh -t script.tcl -project top -revision first

Improving the Sample Code

There are a variety of ways the example code can be modified to add checks and improvements.​

Simple Error Checking

The project_open command generates an error if the specified project does not exist. Use the project_exists command to check whether it exists before opening it, as shown in this example:

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if { ![project_exists $opts(project)] } {
    post_message -type error "Project $opts(project) does not exist"
    exit
}

project_open $opts(project) -revision $opts(revision)

Handling Unspecified Revision Names

You can also modify the example code to handle cases when a revision name is not specified as a command-line argument. With some of the code examples below, you need to specify a revision name only if there is more than one revision in your project. With others, the code can automatically open certain default revisions even if there is more than one revision in your project.

The Quartus II Tcl command project_open defaults to opening a revision with the same name as the specified project if no revision name is specified with the -revision option. This example illustrates the default functionality of the project_open command.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if { [string equal "" $opts(revision)] } {
    project_open $opts(project) -revision $opts(project)
} else {
    project_open $opts(project) -revision $opts(revision)
}

You can use the following code examples to modify that behavior in various ways that save time when you run scripts. These examples determine when no revision name is specified as a command-line argument and use other ways to determine a revision name to use with the -revision option for the project_open command.

Default to a Revision Name

You can use the following code to open a project with only one revision when a revision name is not specified as a command-line argument. Projects with a single revision usually have the same revision and project names, but that is not required. Using the project_open command without a -revision option generates an error when the project's revision name does not match the project name.

This example uses the get_project_revisions command to retrieve a list of all the revisions in the specified project. If there is only one revision (the list length is 1), the script uses that revision name to open the project. Using the list of revision names guarantees the project will open properly, even if the revision name is different than the project name.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if { [string equal "" $opts(revision)] } {
    set revisions [get_project_revisions $opts(project)]
    if { 1 == [llength $revisions] } {
        set opts(revision) [lindex $revisions 0]
    } else {
        post_message -type error \
            "More than one revision in project \
            $opts(project)."
        exit
    }
}

project_open $opts(project) -revision $opts(revision)

Default to the Current Revision

You can use the following code to open a project and default to the current revision, if you do not specify a revision name as a command-line argument. The current revision is the revision you worked with last before closing the project. In a project with one revision, that revision is always the current revision. This example uses the get_current_revision command to retrieve the current revision name for the specified project.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if { [string equal "" $opts(revision)] } {
    set opts(revision) [get_current_revision $opts(project)]
}

project_open $opts(project) -revision $opts(revision)

Print Revision Names

In some cases, you may want to require a revision name if there is more than one revision in a project, and if none is provided, see a list of revision names. You can use the following code to print out all revisions when a revision name is not specified as a command-line argument, and there is more than one revision in the project. This example uses the get_project_revisions command to retrieve a list of all revisions in the project.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if { [string equal "" $opts(revision)] } {
    post_message "You did not specify a revision name.
    set revisions [get_project_revisions $opts(project)]
    if { 1 == [llength $revisions] } {
        set opts(revision) [lindex $revisions 0]
        post_message "There is one revision $opts(revision)"
    } else {
        post_message "These revisions exist in the project:"
        foreach revision $revisions {
            post_message "$revision"
        }
        exit
    }
}

project_open $opts(project) -revision $opts(revision)

Combined Examples

These examples illustrate how to combine some of the improvements described above.

Example 1

The following simple example verifies the specified project exists. If there is no revision name specified as a command-line argument, it opens the current revision. Otherwise it opens the project with the revision name specified as a command-line argument.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if {[project_exists $opts(project)]} {
    if {[string equal "" $opts(revision)]} {
        project_open $opts(project) -revision \
            [get_current_revision $opts(project)]
    } else {
        project_open $opts(project) -revision $opts(revision)
    }
} else {
    post_message -type error "Project $opts(project) does not exist"
    exit
}

Beginning with version 4.1 of the Quartus II software (version 3.0 of the ::quartus::project package), the project_open command supports the -current_revision option. If you use version 4.1 or later of the Quartus II software, you can replace the following command in the above script

project_open $opts(project) -revision \
            [get_current_revision $opts(project)]

with this command

project_open $opts(project) -current_revision

Example 2

The following example combines a number of the improvements illustrated above. It verifies the specified project exists, and opens it if there is only one revision. If there is more than one revision, it prints a list of the revisions and exits.

package require cmdline
set options {\
    { "project.arg" "" "Project name" } \
    { "revision.arg" "" "Revision name" }
}
array set opts [::cmdline::getoptions quartus(args) $options]

if { ![project_exists $opts(project)] } {
    post_message -type error "Project $opts(project) does not exist"
    exit
}

if { [string equal "" $opts(revision)] } {
    post_message "You did not specify a revision name.
    set revisions [get_project_revisions $opts(project)]
    if { 1 == [llength $revisions] } {
        set opts(revision) [lindex $revisions 0]
        post_message "There is one revision $opts(revision)"
    } else {
        post_message "These revisions exist in the project:"
        foreach revision $revisions {
            post_message "$revision"
        }
        exit
    }
}

project_open $opts(project) -revision $opts(revision)