digilent-vitis-scripts

This is a repo for the new Vitis Unified IDE; it contains solutions for check in/out workflow. The checkin/out scripts will handle all the necessary tasks to ensure a smooth workflow for development of projects.

Note #1: To add this repository to a parent repository as a submodule, first open a terminal with access to git. Adding the scripts path argument to the command is recommended in order to keep file paths short.

git submodule add https://github.com/Digilent/digilent-vitis-scripts scripts

git -C scripts checkout new_vitis/master

Note #2: The checkout/checkin scripts need to have src directory in the same folder as the scripts submodule, populating it as below:

• One folder per hardware platform
  • The XSA file describing the hardware specification that the software targets, exported from Vivado.
• One folder per application project, containing the following:
  • A comp-settings.json file with user settings and relative path to XSA file used by a project.
  • A src directory with source files and cmake, linker scripts.

Note that the name of each folder is used in checkout to determine the name of the app/platform/domain.

Note #3: The ws workspace folder generated by checkout.py is a sibling of the src/scripts folders, one level above scripts, so this repository's own .gitignore cannot exclude it from the parent repository. checkout.py automatically adds (once, if not already present) an ignore rule for it to that parent repository's top-level .gitignore the first time it (re)creates ws, keeping the generated workspace's build artifacts out of git status while still tracking the checked-in cleanup.cmd/cleanup.sh/.keep placeholders.

Special Note: Vitis Unified IDE creates a .lock file which after the IDE is closed or another Vitis TCP/IP server is stopped, it will have its file descriptor still hooked up to the previous process. Therefore, between consecutive checkout.py runs/checkin.py runs/Vitis Unified IDE closing leave at least a few seconds.

---

Quick Checkout Guide

1. Some Digilent Github repositories also require that you check out a specific demo branch. Whenever checking out a demo branch, submodules should be updated and initialized:

   git submodule update --init [--recursive]

2. Close Vitis Unified IDE, if you have it open.

3. If you ran the checkout.py script before for the same project, please make sure you delete the ws folder from sw.

4. The scripts present in this repository can be run through the use of the Vitis Commandline Tool 202x.y, which comes along with Vitis. To recreate the workspace, enter the following command into the Vitis Commandline Tool, specifying the absolute path to the checkout script:

   run <path-to-scripts-repo>\checkout.py

   This process will populate the workspace with projects containing sources from the parent repository's src folder, configure those projects, and fully build them. This may take several minutes to fully complete. When the script is finished running, the "Build Finished successfully" message will appear in the command line, followed by the Vitis [idx]: prompt, where idx - 1 is the number of inserted commands.

   The above functionality can be reproduced from Vitis Unified IDE launching the terminal from Terminal -> New Terminal which uses the default command line executable from the OS. If this is the chosen method, then it will be necessary to give absolute path to the checkout.py file, not relative:

   vitis -s <path-to-scripts-repo>\checkout.py

   Alternatively, you can change the Vitis Unified IDE current working directory to the branch's sw submodule and then specify the path to the checkout script as scripts\checkout.py.

   Note: The current working directory is irrelevant to the functionality of the scripts in this submodule.

5. Close the Vitis Commandline Tool/Vitis Unified IDE window which you used to recreate the workspace.

6. Open Vitis Unified IDE either through Vivado's Tools menu, either on its own, and set the Vitis workspace to the repository's sw -> ws folder. From this point, the demo can be programmed onto a board, sources can be viewed and modified as desired.

---

Quick Checkin Guide

Important: The checkin.py can be used multiple times, it will overwrite the existent files and if some new ones appear into an application they are going to be copied too.

Note: This section assumes that you have already created a Vitis workspace containing one or more application projects.

Note: The checkin script has only been tested with standalone application projects at time of writing.

1. Close Vitis Unified IDE, if you have it open.

2. The scripts presented in this repository can be run through the use of the Vitis Commandline Tool 202x.y, for example 2025.1, which comes along with Vitis. To backup the workspace, enter the following command into the Vitis Console, giving it the absolute path to the checkin script:

   run <path-to-scripts-repo>\checkin.py

   The above functionality can be reproduced from Vitis Unified IDE by launching the terminal from Terminal -> New Terminal which uses the default command line executable from the OS. If this is the chosen method, then it will be necessary to give absolute path to the checkin.py file, not relative:

   vitis -s <path-to-scripts-repo>\checkin.py

   Alternatively, you can change the Vitis Unified IDE current working directory to the branch's sw submodule and then specify the path to the checkin script as scripts\checkin.py.

3. Close the Vitis Commandline Tool/Vitis Unified IDE window which you used to run the checkin script. You can now use the Git bash to check what files under the src folder have been changed and what you would need to commit to Git.

---

Quick Programming Guide

program.py programs the board from an app's Vitis launch configuration, without opening the Vitis Unified IDE. It reads ws\<app>\_ide\launch.json, so run checkout.py first.

Note: Supports Zynq-7000 and Zynq UltraScale+ (the family is taken from the launch configuration). Only the ZynqMP flow is validated on hardware. Versal is not supported. There is no UART option; use a terminal program such as PuTTY.

1. Connect and power the board, and close any tool holding the JTAG cable.

2. Run the script through a launcher. By default it resets the system, programs the bitstream, initializes the PS (psu_init/ps7_init, or the FSBL, as set in the launch configuration), downloads the app ELF and runs it:

   <path-to-scripts-repo>\_vitis.bat -v <version> -s program.py

3. Typical variations:

   <path-to-scripts-repo>\_vitis.bat -v <version> -s program.py --elf-only (reuse the current PS/PL state)

   <path-to-scripts-repo>\_vitis.bat -v <version> -s program.py --app <app-name> (when ws has several apps)

   <path-to-scripts-repo>\_vitis.bat -v <version> -s program.py --dry-run (print the steps only)

   <path-to-scripts-repo>\_vitis.bat -v <version> -s program.py --reset-ps (reset the PS only, the PL is kept)

   <path-to-scripts-repo>\_vitis.bat -v <version> -s program.py --reset-cpu (reset only the processor core(s); --core selects one)

4. Output:

   • The terminal shows the programming steps and errors.
   • ws\program.log (appended) also holds the xsdb output, e.g. the downloaded sections.
   • ws\hw_server.log holds the hw_server log. The script starts hw_server when none listens on the port, and stops it when it exits.

Note: The app is picked automatically from the only ws\<app>\_ide\launch.json (platform FSBL apps are ignored). With two or more apps, --app is required.

---

Running Scripts Without Vitis Environment Variables

Note: _vitis.ps1 / _vitis.bat / _vitis.sh are OS-native launchers that mimic vitis -s <script> without Vitis on the PATH or any Vitis environment variables set. They can be run from any directory; a relative -s script path is resolved against the launcher's own location.

1. Pick the launcher matching your OS: _vitis.ps1 or _vitis.bat on Windows, _vitis.sh on Linux.

2. The launcher locates a Vitis install on disk (legacy Xilinx and post-2025.1 AMDDesignTools root folders; all Windows drives, or /opt, /tools, $HOME on Linux) and runs the bundled Python interpreter directly, with the PYTHONPATH needed to import vitis.

3. Pass the options below, in the shape <launcher> -v <version> -s <script> [script-args]:

   • -v (-Version): Vitis version to use, e.g. 2025.2.
   • -i (-InstallPath): install root to search first, useful when several versions/vendors are installed side by side.
   • -s (-Script): script to run. If omitted, only the resolved Vitis, python and PYTHONPATH info is printed, which is handy to check what -v/-i resolve to.
   • --stop-dangling: stop leftover Vitis processes (e.g. a server still holding the .lock file, see Special Note above) before running. Only processes launched from the resolved Vitis install are stopped.
   • Any remaining arguments are forwarded to the script.

   Note: The long names (-Version/-InstallPath/-Script) exist only in _vitis.ps1; _vitis.bat/_vitis.sh accept just the short -v/-i/-s forms.

4. Examples (run from any directory):

   <path-to-scripts-repo>\_vitis.ps1 -v <version> -s checkout.py

   <path-to-scripts-repo>\_vitis.bat -v <version> -s checkin.py

   <path-to-scripts-repo>/_vitis.sh -v <version> -s checkout.py

5. The same logic, plus process management and platform XSA update/upgrade helpers, is available from Python in misc.py.

---

Command Reference (copy/paste, replace placeholders as needed)

Note: Replace <version> with the installed Vitis version (e.g. 2025.2), <install-path> with an install root to search first, and <path-to-scripts-repo> with the absolute or relative path to this repository (the scripts submodule). The launchers can be run from any directory. -s is resolved relative to the launcher's own directory, so pass a bare checkout.py/checkin.py/program.py, never prefixed with <path-to-scripts-repo>.

checkout.py flags (combinable):

• --platform <platform-name>: rebuild only this platform, plus its apps (repeatable).
• --app <app-name>: rebuild only this app, plus its platform (repeatable).
• --skip-unbound-platforms: skip platforms no app references.
• --incremental: rebuild in place; only with --platform/--app.
• --allow-process-cleanup: allow stopping pre-existing Vitis processes.
• -y/--assume-yes: skip the wipe confirmation prompt (CI/unattended).
• --esw-repo <path>: custom embeddedsw checkout; default is the one bundled with Vitis.

checkin.py flags (combinable):

• --port <port-number>: Vitis server port; auto-selected if omitted.
• --ip <ip-address>: Vitis server host; defaults to localhost.

program.py flags (combinable):

• Selection: --ws <path>, --app <app-name>, --config <name> (launch configuration).
• Steps: --reset-ps (PS reset only), --reset-cpu (processor reset only), --elf-only, --no-reset, --no-bitstream, --no-init, --no-run, --stop-at-entry.
• PS init mode: --psu-init (alias --ps7-init, --ps-init) or --fsbl; default from launch.json.
• Overrides: --family {zynq,zynqmp}, --elf, --core, --bit, --xsa, --init-tcl, --fsbl-elf, --fsbl-exit.
• Connection: --cable <name-substring>, --host, --port, --timeout <s> (FSBL run).
• Extras: --build (rebuild the app in ws first; it does not sync src like checkout.py), --watch (reprogram the ELF when it changes), --list-targets, --dry-run, --log <file>.

Windows (_vitis.bat):

:: full wipe + rebuild of every platform/app
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py

:: rebuild only this platform (+ any app bound to it)
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py --platform <platform-name>

:: rebuild only this app (+ its resolved platform)
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py --app <app-name>

:: rebuild only this explicit platform+app pair
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py --platform <platform-name> --app <app-name>

:: rebuild this app in place (re-sync + incremental cmake build, no delete/recreate)
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py --app <app-name> --incremental

:: full run, but skip platforms not referenced by any app's comp-settings.json
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py --skip-unbound-platforms

:: rebuild only this platform, still skipping other unbound platforms
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkout.py --platform <platform-name> --skip-unbound-platforms

:: back up the current workspace's sources into src\
<path-to-scripts-repo>\_vitis.bat -v <version> -s checkin.py

:: program the board from the app's launch configuration
<path-to-scripts-repo>\_vitis.bat -v <version> -s program.py

:: only download and run the ELF, selecting the app
<path-to-scripts-repo>\_vitis.bat -v <version> -s program.py --app <app-name> --elf-only

:: only stop leftover Vitis-install-scoped processes (no script run)
<path-to-scripts-repo>\_vitis.bat -v <version> --stop-dangling

:: search a specific install root first, then run checkout.py
<path-to-scripts-repo>\_vitis.bat -v <version> -i <install-path> -s checkout.py

Windows (_vitis.ps1):

# full wipe + rebuild of every platform/app
<path-to-scripts-repo>\_vitis.ps1 -v <version> -s checkout.py

# rebuild only this platform in place (incremental)
<path-to-scripts-repo>\_vitis.ps1 -v <version> -s checkout.py --platform <platform-name> --incremental

# only stop leftover Vitis-install-scoped processes (no script run)
<path-to-scripts-repo>\_vitis.ps1 -v <version> -StopDangling

Linux (_vitis.sh):

# full wipe + rebuild of every platform/app
<path-to-scripts-repo>/_vitis.sh -v <version> -s checkout.py

# rebuild only this app in place (incremental)
<path-to-scripts-repo>/_vitis.sh -v <version> -s checkout.py --app <app-name> --incremental

# only stop leftover Vitis-install-scoped processes (no script run)
<path-to-scripts-repo>/_vitis.sh -v <version> --stop-dangling

---