qed::fork_new_seeds (::quartus::qed)

Belongs to ::quartus::qed 1.0

Creates a set of new revisions within a connected project and initializes a new
project object for each one. The new objects are then connected and the value of
the "SEED" global assignment is modified accordingly. Each new object will inherit
its "groups" property from the source project object.

The "-num_seeds" argument dictates how many revisions to create and connect. The seed
values will be the next in line after the value of the source project's seed. For
example, if the source project used a seed of 4 and -num_seeds 3 is specified, the
returned projects will have seeds 5, 6, and 7 set, respectively.

The compilation database associated with the returned projects will not be
complete. Run "qed::compile" to generate a complete database for each
new revision.

The "-revision_pattern" option must specify a unique and new name for each revision
to generate within the remote project. This command will return an error if
a revision cannot be created successfully. In order to guarantee this uniqueness, the
seed value may be incorporated into the generated revision by including the substring
"%SEED%" into the -revision_pattern value. This substring will be replaced with the unique
seed that will be set once the revision is created. For example, if the original project
had a seed value of 4, -num_seeds 3 is specified, and the -revision_pattern argument is
set to "seed_%SEED%", the resulting revisions will be named "seed_5", "seed_6" and "seed_7"
respectively. Note that the revision names are visible via the returned project objects'
"revision" property. To name the new revisions after the original project's revision,
include the substring "%ORIGINAL_REVISION%" in the -revision_pattern argument.

Each new revision will be based on the revision that the connected project is accessing,
which means it inherits all settings and assignments from that source revision except
that it will have a different value set for the "SEED" global assignment.

The "-id_pattern" option controls each "id" property of the project objects which are created
when this command completes. These IDs must be unique within the workspace. In order to
guarantee this uniqueness, the seed value may be incorporated into the generated ID by including
the substring "%SEED%" into the -id_pattern value. This substring will be replaced with the unique
seed that will be set once the revision is created. For example, if the original project
had a seed value of 4, -num_seeds 3 is specified, and the -id_pattern argument is
set to "seed_%SEED%", the resulting projects will have IDs of "seed_5", "seed_6" and "seed_7"
respectively. To derive the IDs of the new projects after the original project's revision,
include the substring "%ORIGINAL_ID%" in the -id_pattern argument.

The "-launch_compiles" option controls whether to automatically launch Quartus Prime compiles on
the forked seeds after their "SEED" global assignments have been updated. "none" prevents any compiles
	from running. "new_only" is equivalent to creating a new group that just contains the new project
	objects and running qed::compile on that group. "all" will include the original project in the
	compilation.

    qed::create_object -type group my_group
    qed::create_object -type project project_A -qpf_path /file/path/to/project.qpf -revision rev_A -groups my_group
    qed::launch_connection project_A -open_project
    qed::run project_A -cmd "set_global_assignment -name SEED 1"

    # Fork one new seed with a specific ID and revision name
    qed::fork_new_seeds project_A -num_seeds 1 -revision_pattern rev_B -id project_B -inherit_groups
    qed::launch_connection project_B -open_project

    # Fork several new seeds and derive IDs and revision names from patterns
    qed::fork_new_seeds project_B -num_seeds 3 -revision_pattern rev_B_%SEED% -id project_B_seed_%SEED% -inherit_groups

    # Returns: {project_A 1 project_B 2 project_B_seed_3 3 project_B_seed_4 4 project_B_seed_5 5}
    qed::run_command my_group -cmd "get_global_assignment -name SEED"