Forum Discussion

Viater's avatar
Viater
Icon for New Contributor rankNew Contributor
7 hours ago

Bug Report: project_open Tcl Command Resets Current Revision to Base Revision in Quartus

Environment Details

Quartus Version: Quartus Prime Lite Edition, Version 24.1std.0, Build 1077 (03/04/2025 SC)

Host OS: Linux Ubuntu 22.04.5 LTS

Component: Quartus Tcl Shell (quartus_sh) / Project Management API

Summary of the Issue

There is a critical discrepancy in how Quartus Prime manages project revisions between the GUI and the Command Line Interface (CLI/Tcl).

When a user changes the current revision of a project via the GUI, the setting is preserved correctly upon GUI restarts. However, if the project is opened via the Tcl shell (quartus_sh) using the project_open command without any flags, Quartus silently resets the current revision back to the base revision.

Even worse, this reset is permanently written back to the project. When the user subsequently reopens the project in the GUI, they will find their revision has reverted to the base revision. This behavior poses a high risk of data loss or unintentional regression, as users may unknowingly compile, modify, or overwrite older base configurations.

Steps to Reproduce

1. Open Quartus GUI and create a project with a base revision (e.g., my_project).

2. Go to Project -> Revisions and create a new revision (e.g., rev_v2). Set rev_v2 as the current revision.

3. Close the project and close the GUI. (Verify that opening the GUI again keeps rev_v2 active—this works correctly).

4. Open your terminal/command prompt and start the interactive Quartus Tcl shell:quartus_sh -s

5. Run the following Tcl command to open the project:project_open /path/to/my_project.qpf

6. Observed CLI Behavior: get_current_revision returns my_project (the base revision) instead of rev_v2.

7. Reopen the Quartus GUI and load the project. Observed GUI Behavior: The active revision is now reverted to the base revision (my_project).

Known Workaround & The Core Discrepancy

I am aware that you can bypass this issue by explicitly passing the current revision flag when opening the project:

project_open -current_revision /path/to/my_project.qpf

Using -current_revision successfully forces the Tcl shell to look up and load the active revision.

However, this does not excuse the default behavior.

Inconsistent defaults: Running a bare project_open <project> command should default to loading the currently set active revision (matching the GUI's load behavior), rather than defaulting to the base revision and silently overriding the .qpf metadata.

Unintentional Mutability: Simply opening a project file in read/query mode in the shell should never silently alter and write back a state change (resetting the revision) to the project configuration files without explicit instruction.

Bizarrely, if you run the tcl command "project_open /path/to/project.qpf" in the GUI it correctly opens into the current set revision. This means there are two different behaviors for the same command between the GUI and shell. 

Expected Behavior

The project_open Tcl command should default to loading the active revision specified in the metadata (matching the GUI behavior) when no revision-specific flags are passed. It should not reset the active revision to the base revision. In general, there shouldn't be a difference in behavior between the shell and GUI with the same TCL command (project_open).

Impact

This is a silent failure that mutates project state. Engineers utilizing hybrid workflows (designing in the GUI but running automated compilation/verification scripts in the shell) will find their project revisions constantly and unexpectedly reverting to older base versions, potentially corrupting active design branches.

Please let me know if this is a known issue.

general

1 Reply

  • ai_responder's avatar
    ai_responder
    Icon for Community Manager rankCommunity Manager
    7 hours ago

    Good write-up — let me clarify what's actually happening here based on the documented API behavior, because it explains both the default you're seeing and points to the right mitigations.

    Why bare project_open picks the base revision in the shell

    This is documented behavior for the ::quartus::project package (the one loaded in quartus_sh). When the -revision option is not specified, the project name is specified as the revision name. project_open (::quartus::project) So a bare project_open my_project will always open the revision whose name matches the project name — it does not look up whatever is marked as the "current revision" in the .qpf unless you tell it to.

    Why the GUI behaves differently

    The GUI uses a separate Tcl package: ::quartus::project_ui. Its project_open variant has a different option set — notably it includes -error_on_incompatible_database instead of -force, and it by default opens the project and overwrites the database created in a different version of Quartus Prime software project_open (::quartus::project_ui) — and internally the GUI application layer likely passes -current_revision when loading a project from the File menu. The shell executable doesn't do that automatically; you have to be explicit.

    The .qpf mutation / revision ordering side-effect

    The ::quartus::project package does document a related behavior: the -preserve_revision_order option prevents moving the revision to the top of the .qpf file and preserves existing revision ordering. project_open (::quartus::project) If you open without this flag, the shell can reorder revisions in the .qpf, which is likely the mechanism behind the "active revision reverts" symptom you're seeing after a shell session.

    Recommended pattern for scripted workflows

    Use both -current_revision and -preserve_revision_order together in any automation script that isn't explicitly switching revisions:

    project_open -current_revision -preserve_revision_order /path/to/my_project.qpf

    For scripts that need to be robust about which revision they operate on, the documented full-featured pattern is:

    package require cmdline
    variable ::argv0 $::quartus(args)
    set options { \
      { "project.arg" "" "Project Name" } \
      { "revision.arg" "" "Revision Name" } \
    }
    array set optshash [::cmdline::getoptions ::argv0 $options]
    if {[project_exists $optshash(project)]} {
      if {[string equal "" $optshash(revision)]} {
        project_open $optshash(project) -current_revision
      } else {
        project_open $optshash(project) -revision $optshash(revision)
      }
    } else {
      puts "Project $optshash(project) does not exist"
      exit 1
    }
    The cmdline Package

    Bottom line: The default-to-project-name behavior is by design in the ::quartus::project package, not a regression. The discrepancy with the GUI is real — the GUI internally uses -current_revision — but it is the result of the two packages (::quartus::project vs ::quartus::project_ui) having different defaults, not a bug in either path per se. The fix for your hybrid workflows is straightforward: always pass -current_revision -preserve_revision_order in your shell scripts unless you intentionally want a specific revision by name.

    If you believe the default behavior of the shell package should be changed to match the GUI, that's a valid product feedback item worth raising through the official support channel as an enhancement request.


    Note: To continue using AI Responder, please start your next inquiry with ai_responder

    Disclaimer (Beta): The AI Responder is currently provided as a beta feature. AI-generated responses may contain errors or omissions. Please verify technical guidance with official Altera documentation before implementation.

    Thank you very much.