Development

This section will help users start creating or managing their own solutions and projects. ZStudio organizes your code in the Solutions and Projects structure, which is fully compatible with Visual Studio.

Solutions and projects

In ZStudio, a solution is a container that includes one or more projects with each project able to be built independently and having its own code and configuration. The solution acts as the top-level container that coordinates and manages dependencies configurations, and build order between multiple projects.

A solution may contain more than one projects, and a single project can be used in multiple different solutions; similarly, the same piece of source code can be used in various different projects.

Projects and project file

A project can only compile into an executable or a library. However, you can create various projects with the same piece of source code to compile into different types of files. ZStudio uses {project_name}.zsproj file type to store configuration for each project in the solution. The .zsproj file contains project properties, as well as the settings for building, running, debugging, and profiling of the project. it's not intended to be edited by hand.

Solutions and solution file

A solution in ZStudio may contain more than one projects. When user open one solution, ZStudio will load all projects it contained. You can handle multiple projects as long as they belong to the same solution, but you cannot have more than one solution in a single session. If necessary, you can simultaneously work with multiple solution in different Windows. ZStudio uses {solution_name}.zssln to organize projects, projects items, and solution items in the solution. When you configure multiple distinct projects to be part of the solution, the text-based file {solution_name}.zssln will automatically update; it's not intended to be edited by hand.

Solution Explorer

Once a solution is created and opened, most of the project/solution management tasks are performed in Solution Explorer. By default, the Solution Explorer displays on the left-hand side panel and contain views of Project Controller, Project Navigator and File Navigator, etc. You can control the default visibility of them with (More Actions...) button in the up-right corner in Solution Explorer view.

The Project Controller contains commonly used tool button for development. The buttons from left to right are Build, Build Configuration, Run, Run Configuration, Debug and Debug Configuration. You can also set active project, configuration, platform and target SoC conveniently through pull-down box in Project Controller.

The Project Navigator in ZStudio looks like a content tree that represents the hierarchical structure of all the items contained in each project in the current solution, which includes Headers node, Sources node, Output node, References node, and Dependencies node.

The File Navigator stored all files of the solution, including solution file {solution_name}.zssln, project files {project_name}.zsproj and all project items.

Quick Start

This section is about how to create solution and project, how to add reference between projects and how to add external dependencies in ZStudio.

Create empty solution

ZStudio supports construct your solution from scratch, you can create solutions that have no projects.

1. On the Project Navigator, click New Solution button or select File > New Solution from menu bar.
2. In the dialog, enter name (Quick_Start as example below) and location values for your solution, and select Create.

Create a project

After you create an empty solution, you can add new project Hello to it by choosing New Project in Project Navigator. On the New Project dialog, you need to enter or select some basic information of name, location, project type, language and toolchain for new project. To add Hello project to current Quick_Start, you need to select Add To Exist on the Solution drop-down box.

Or you can also add existing project in current solution by clicking Add Project and specify its path on your local file system.

when a user creates a new project without an existing solution, ZStudio will automatically generate a solution with the same name as the project to serve as a container, which ensures that there is still a management structure for the project.

Add project code to build and run

Start with an empty Hello project, you can add items you need. Right-click Sources node and select New Source File from the context menu. Or directly click "+" to create a source file. On the dialogue, you need to enter the name main.c and location value. The file opens in the editor bearing a tab main.c automatically, allowing you to begin coding.

main.c

#include <stdio.h>
#include <stdlib.h>

int main()
{
   printf("Hello World\n");
   return 0;
}

Click Build button in Project Controller. Check the build process and result in Build Console in bottom panel.

Click the Run button in Project Controller and check the output displayed in Run Console in bottom panel.

Add project reference

Solutions commonly contain more than one project, and these projects sometimes reference each other. Some projects in a solution might be libraries, some might be executable project. To add reference between projects, you need to create another Add project first.

1. From the right-click menu of Project Navigator in Solution Explorer, select New Project or hover over Project Navigator and click + button.

   In the New project dialog box, name the project Add, select Static Library project type and select Add To Exist solution.

2. Then you can add code in the Add project.

   Right-click Headers node and select New Header from the context menu. On the dialogue, you need to enter the name add.h and location value for header file. The file opens in the editor, you can add your code and save it.

   add.h

   int add(int num0, int num1);

   The add.h can be found in Headers node.

   Right-click Sources node and select New Source File from the context menu. On the dialogue, You need to enter the name add.c and location value for source file. The file opens in the editor, allowing you to begin coding. Here is a simple function definition of addition expression.

   add.c

   int add(int num0, int num1)
   {
      return num0 + num1;
   }

   The add.c can be found in Sources node.

3. Add reference between projects

   Adding the reference creates a build dependency between the two projects, meaning that when you build the solution Add builds before Hello.

   Right-click the References node of the Hello project, and select Manage reference from the context menu.

   In the Manage Reference dialog box, select Add project. In the Link Library Dependency pane, specify whether to link the .lib files that are produced by dependent projects. Select True from drop-down box, and then click Save. A reference to the Add project appears under the Hello project.

4. To check that the reference is working, Set Hello as active project and click Build. The Build Console opens, and you can see that build finished successfully, which means the reference is working.

   warning

   You need to go Build > Clean before rebuild the project when you only make changes in your header file without changing your source code.

5. Click Run to check the output.

info

The reference will create a process to link static library into final executable file, which doesn't display in compiler include path list of project Build Configuration.

Add project dependency

When building a solution for SoC or development board, you must use additional software packs to work with those projects. Project Dependencies can be board support packs or library packs. To add dependencies to a project:

1. In Project Navigator, select a project.

2. Unfold tree menu, right-click the Dependencies node and select Manage Dependency.

3. Find the packs (include the imported packs) in Pack List, double-click pack to add them in Dependency List.

   The SoC search bar automatically filled in the value you selected in Project Configuration. You can search and discover the packs using the Arch search bar, it will not only show the packs matching your criteria, but also filter out those which are not matching. This makes finding packs quick and easy.

4. From Dependencies List, you can switch the build order and link order of the packs or remove them and view the order in this list or Dependencies node.

   All packs added to project appears under Dependencies node in Solution Explorer.

Upload and download projects (ZStudio Cloud)

ZStudio Cloud supports uploading local ZStudio projects to the cloud for cross-platform development, as well as downloading cloud projects to local machine.

Upload projects

To upload a project, select File > Upload Project/Solution from the main menu, specify the compressed file that you want to upload from local file system. Supported file formats include .tar, .tar.gz, .tar.bz2, and .zip.

In the dialog box, specify the save path for the uploaded project and an extraction prompt will appear. Once extracted, the project can be opened and used as usual.

Download projects

ZStudio Cloud allows you to download projects to your local device. In the File Navigator, right-click on the Project/Solution node and select Download. ZStudio Cloud will package the entire solution as a compressed file, and you can complete the download by specifying the location on your local PC where the compressed file should be saved.

ZStudio Cloud also supports downloading output files and save in local PC file system. Right-click the file under output node in File Navigator and specify the directory.

Import example solutions

ZStudio contains a number of demos which can be opened simply by Import Example Solutions option.

On the ZSolution main menu, click File > Import Example Solutions to select one demo from pull-down box. Specify the destination and name of solution in the evoked dialog if needed and click Open.

The example solution will be loaded in current window.

Clone from repository

You can clone a project directly from ZSolution and create a new solution based on it.

1. Go to File > Clone from Repository.

2. Specify the URL of the project repository you want to clone. If the repository you specified contains sub repositories, you need to check the Recursively Clone.

3. In the Directory field, enter the path to the folder where your local Git project will be created, then click Clone.

   

   

You can check the cloning process in the notification window on bottom-right corner.

When finished, select one of the options to open:

• Import as a Makefile project: if the project you cloned is managed by Makefile, you can choose this option, refer to Import Makefile project.

• Import as a CMake project: if the project you cloned is managed by CMake, you can choose this option, refer to Import CMake project.

• Create an Empty Solution for the Repository: ZStudio will create a solution to serve as a container for the project.

• Find Virtual Board Files and Open with ZExplorer: if you clone config files for ZVB, you can choose this option.

Import Makefile or CMake project

Complete support for Makefile or CMake projects in ZStudio is still a work in progress. Welcome to leave your feedback in 1nfinite.

Import Makefile project

To import a Makefile project:

1. Select File > Import Makefile project from the main menu.

   

   

   Makefile Project Configuration

   • In dialog, point ZStudio to the top-level folder of existing project. Click the browse button to find the desired project in your file system and click "Select Folder".

   • ZStudio will automatically detect and recognize entry Makefile in the path as the entry point. You can also specify the Makefile inside project directly.

   • Add Make arguments such as TOOLCHAIN=terapines. These arguments are used by ZStudio when calling the make command on the step of extracting project information.

   • Make Clean Arguments: Specify clean arguments to clean up the project if the imported project has been compiled with make command and remain intermediate code files.

     tip

     Cleaning is required for the project load because it ensures a clean and reliable build environment, considering changes in dependencies or file structure, and helps in achieving consistent and predictable builds. Empty argument may cause importing fail. However, ZStudio will only clean the imported project and will not affect the original project.

   • When dealing with non-compilation commands that cannot be determined, ZStudio provides the following options:

     • Execute before the next compile command: these commands will be executed before the next compilation command.
     • Execute after the previous compile command: these commands will be executed after the completion of the previous compile command.
     • Discard: the undetermined commands will be ignored, and no special handling will be performed.

   • The import process will generate some configuration files for the project. You can either import the original project or a copied version.

     • Make a copy: If you want keep your original project as unchanged, you need to choose "Make a Copy" here, but the importing process would be longer.
     • Use the Original Project: If you want a quick importing process and don't mind the changes on original project, you can choose "Use the Original Project" here.

2. Click Import and a notification will prompt from message window to remind you adjust project configuration. If there are some some incompatible options in tool settings in the imported project, the Fix Makefile project option in the dialog is recommended.

   Search and select Fix Makefile Project in Command Palette Ctrl+Shift+P can evoke the window again.

tip

Please refer to ZCC user guide and other toolchain's doc to fix incompatible options in tool settings.

The Makefile project will load in ZStudio when the importing process finished.

warning

When using a project across different platforms, use forward slash (/) as the path separator in Linux, while backslash (\) in Windows. Please fix path separator in Makefile file before importing. You can also use Fix Makefile Project option to fix this problem.

Import CMake project

To import a CMake project:

1. Select File > Import CMake project from the main menu.

   

   

2. In dialog, configure CMake profile settings.

   CMake Project Configuration

   • Project Root Path: Specify here the top-level folder of your CMake project.

   • CMake Work Directory: Specify here the desired location for the generated CMake files. The build directory is recommended. You can create a build folder under the project root before importing it.

   • CMake Arguments: In this field, specify specify the complete CMake options required for the project generation, separated by spaces. Since ZStudio uses Make as the build tool, avoid using parameters such as -GNinja.

   • Environment Variables: Click + to invoke the Add Environment Variables pane and specify there the environment variables to be passed to CMake on the generation phase.

   Other settings is as same as importing Makefile project.

3. Click Import and check the process in Run Console.

Delete a solution, project, or item

To delete a solution or other components, use File Explorer in Windows to delete the folder that contains the .zssln solution files. You can access File Explorer in Windows by using Solution Explorer in ZStudio.

1. In File Navigator, on the right-click context menu of the solution you want to delete, select Reveal in File Explorer.

2. In File Explorer, select the solution folder, and then press Delete.

Delete project or item

To delete a project from your solution, you can select Delete or Delete Project on the right-click menu of the project you want to delete in File Navigator or Project Navigator. You can also use File Explorer in Windows.

Remove project or item

You can use the right-click context menu in Project Navigator to remove projects or items in ZStudio, but that only removes it from the Project Navigator view rather than delete them in File Navigator or solution folder in your system.

To restore projects that removed from Project Navigator, hover over Project Navigator and click (Add project) button. You need to point ZStudio to the project ({project_name}.zsproj) you want to restore and open it.

Pack management

The Pack Manager is a utility for managing packs in ZStudio, which supports installing multiple versions of packs that are designed to provide optimized functionalities and tools for specific domains or suitable for specific SoC or Development Board.

On the main menu, select Tools > Pack Manager > Open Pack Manager to invoke the pack management panel. You can use the buttons in Packs panel to:

• Install : Download the pack from the internet and install it locally.
• Uninstall : Removed the installed pack. It can be reinstalled if required.

ZCC packs

ZCC toolchain by default included libzcc with base ISAs. For additional packs that are designed to provide optimized functionalities and tools for specific domains (e.g. dsp or nn), choose to install by pack manager. The downloaded libraries would be added in toolchain and apply globally.

• libzcc: standard C and C++ libraries, including newlib, compiler-rt and libc++
  • newlib: Implementation of the standard C library intended for use on embedded systems.
  • compiler-rt: Runtime library includes built-in functions and routines necessary for efficient execution of compiled code.
  • libc++: Implementation of the C++ standard library and is designed to be highly optimized and standards-compliant.
• libdsp: It offers a collection of functions and tools specifically designed for digital signal processing (DSP).
• libnn: Specialized library for implementing and running neural network (NN) algorithms.

Vendor packs

The left side of the Pack Manager lists devices grouped by SoCs and Development Boards. The right side lists device-specific software packs, generic software packs and imported packs that can be installed to use with your project. The installed packs are under Users\{User_name}\ZStudio\Packs. you can add them to your projects, see also Add project dependencysection.

You can use search bar to narrow the pack list. The left side filter of the Pack Manager allows you narrow the list of SoCs or boards. If you enter N300, that will match every device which name include N300 in the list, such as N300, N300f and N300fd. The right side filter allows you search across pack type. If you enter mac, that will match every pack which name include mac in the list.

Import custom software packs

ZStudio supports importing local packs. You can either import the pre-compiled library or the actual source code of the library to work with you project.

• Static Library: adds a pre-compiled .a library to the pack manager.
• Source: adds the actual source code of the static library as a pack to the pack manager.

Import pre-compiled library

The pre-compiled library you imported can be directly link against for your project, which is easier and faster for large libraries :

1. On the main menu, select Tools > Pack Manage > Import Pack to invoke the importing dialogue.

2. Provide the pack root path and select Static Library from pack type drop-down box.

3. Provide the absolute path of .a library.

4. Specify the Arch, ABI and CPU to the pack, which can help you to match packs with specific SoC target in project development.

Import the source code of library

Importing the source code of static library give you full access to the library's source code:

1. On the main menu, select Tools > Pack Manage > Import Pack to invoke the importing dialogue.

2. Specify the pack root path and select Source from pack type drop-down box.

3. ZStudio will automatically detect and recognize entry Makefile in the pack root path as the entry point. You can also specify that Makefile directly.

4. Add Make arguments and select how to configure commands unrelated to the compilation process.

   • Execute before the next compile command: these commands will be executed before the next compilation command.
   • Execute after the previous compile command: these commands will be executed after the completion of the previous compile command.
   • Discard: the undetermined commands will be ignored, and no special handling will be performed.

warning

When importing the source code of library across different platforms, use forward slash (/) as the path separator in Linux, while backslash (\) in Windows. Please fix path separators in Makefile before importing.

You can find the imported packs in Pack Manger panel. The imported packs will be stored under Users\{user_name}\ZStudio\Packs. You can also add them to your projects, see also add project dependency section.

Export project as a pack

The static library project exported as a pack can be reused in your local ZStudio or other desktop or cloud version. You can add it in your project dependencies to compile and link it with your project. To export project as a pack:

1. Right-click the static library project in Project Navigator and select Export as a Pack in context menu.

2. You can either export the project as pre-compiled library or the source code folder of the library to work with you project.

   • Source: The project exported as source pack can be reused with full access to library's source code, allowing you to modify it if necessary and debug it more easily. You can select multiple configuration and specify one of them as active to export.

   • Static Library: The project exported as static library pack can be reused with pre-compiled library that your program can directly link against. Usually, the value of Arch, ABI and CPU will be automatically filled in according to the project configuration. You need to specify the pre-compiled library path which is by default generated under {project_name}\output.

3. Click Export and wait for the Successfully exported pack prompted from message window.

You can find the imported packs in Pack Manger panel. The exported packs will be stored under Users\{user_name}\ZStudio\Packs.

Source control

ZStudio has integrated source control management(SCM). Please make sure Git is installed. ZStudio will use your machine's Git installation. And we assume you are already familiar wit Git.

Initialize a repository

The Source Control view will give you the option to when it haven't find a folder yet. If you project is on local, you can click Initialize Repository button to create a Git repository. Running Initialize Repository will show your project files as untracked changes ready to be staged.

Changes

The Source Control icon in the Activity Bar on the left will always indicate an overview of how many changes you currently have in your repository. Selecting the icon will show you the detail of your current repository changes: CHANGES, STAGED CHANGES and MERGE CHANGES.

The change list shows all files that have been modified since you last synchronized with the remote repository. You can use Stage option for files you want to add to your next commit. The statuses are displayed to the right of each files to indicate changes. There are five types of change marks:

• M (Modify): Files that have been modified in either the CHANGES or STAGED CHANGES list.
• D (Delete) : Files that have been deleted.
• U (Untracked) : Files that added and not yet staged in CHANGES list.
• A (added) : File that added and saved in STAGED CHANGES list.
• C (Merge Conflict): You need to resolve it before you can push.

Hover the mouse cursor over the file in CHANGES to display the operation buttons besides files. These buttons are, from left to right:

• Discard Changes: Revert changed files to their states as of the last time they were pushed (or their starting state if they have never been pushed).
• Open File: Open file in editor.
• Stage Change: Use Stage option for files you want to add to your next commit.

Hover the mouse cursor over the file in STAGED CHANGES to display the operation buttons besides files. These buttons are, from left to right:

• Open File: Open file in editor.
• Unstage Change: Return a staged file to CHANGES list.

With the (Toggle to List View) and (Toggle to Tree view) buttons, you can display your changes as a list or as a tree view.

Commit

Staging files can control which of your edited files are added into each commit. This manually breaks your work into logical units, each in its own commit, rather than having to commit all files together. You can always remove a file from the STAGED CHANGES list, and later add it to a different commit.

To commit changes:

1. In the Source Control view, all new and modified files are listed under CHANGES.
2. Hover your mouse over the file you want to commit and click + to stage your changes. To stage several files at once, hold Ctrl and click the files you want to stage, then click +.
3. Type a commit message in the box and click the (Commit) button to commit them.
4. To push the commit to the remote branch, click (More Actions...) on the up-right corner and select Push.

Synchronizing

If the remote repository has been changed since you last pulled, you must synchronize your local copy before you can push any of your own changes to the remote.

The Synchronize Changes indicators on the status bar show how many changes have been pushed to the remote repository since your last pull, and how many commits you have on your local copy. The Synchronize Changes indicators are also a button that displays the available synchronization options.

• Up arrow: how many commits you have on your local copy
• Down arrow: how many changes have been pushed to the remote repository since your last pull

Resolve merge conflicts

Synchronizing remote and local changes by pulling can lead to merge conflicts when a single file has been edited in both locations. Merge conflicts can also happen when you apply or pop a stash, if the stash contains changes that contradict further work on the branch.

By default, when Git sees a conflict between two branches being merged, it will add merge conflict markers <<<<<<< ======= >>>>>>>into your code and mark the file as conflicted and let you resolve it.

The <<<<<<< part of a conflict is the branch you are merging into (shows your local changes), and the >>>>>>> part is from the commit that you are trying to merge in (shows the remote changes which you were trying to merge in). In order to resolve a conflict, you have to decide which part you want to keep or merge the contents yourself, and then remove all the merge conflict markers. Once you are happy with the corrections on a given file, click "+" to stage your changes.

Create or switch branches

Git uses branches to manage the different version of source code. It isolates your work from other people's work or from code that needs to remain stable. ZStudio allows creating branches, as well as synching the remote and local branches.

You can see which branch you are working on from the status bar (when first setting a repository, you are on the master branch by default).

To create a new branch or switch to a different branch:

1. Click the current branch in the status bar. The available branches are listed at the top of the window.

2. Create or switch:

   • To create a new branch: Select Create new branch... and enter a name.

   The branch is created locally; it will be published to the remote repository the first time you push from it.

   • To switch to a different branch, search for and select an existing branch in the list.

You can also create and checkout branches in Command Palette. Press Control+Shift+P to brings up the Command Palette, and input Git: Checkout. You will see a dropdown list that give you the option to create a new branch or checkout a branch.

Extensions

Extensions are a mechanism to add additional features to support your development workflow into ZStudio and they can be installed at runtime or from VSIX. This section explains how to find, install, use and manage extensions in ZStudio.

Install extensions

You can search and install extensions within ZStudio.

1. Bring up the Extensions view by clicking on the in the Activity Bar or use the shortcut Ctrl+Shift+X.

2. Find the extension you want via search bar. All the available extensions are listed under Open VSX Registry, the open-source extension marketplace operated by the Eclipse Foundation. Each extension in the list includes a brief description, the publisher and the install button. You can select the extension item to display the extension's details page where you can learn more.

3. For example, let's install the Draw.io Integration extension. It can create a diagram or edit .drawio files. Click the Install button and ZStudio will download and install the extension from the Open VSX Registry.

4. When the installation is complete, you can create a drawio file and open it in ZStudio to experience its feature.

   

5. You can install the other versions from the gear button context menu, or you can uninstall it if you don't need it anymore. Uninstall action will prompt you to reload the current window.

   

Install from VSIX

You can manually install a extension package in a .vsix file. This way enable you to install extensions beyond Open VSX Registry.

1. Find and download the extension package you want. For example, download Rainbow Brackets extension from VSCode marketplace. It provides rainbow colors for the round brackets, the square brackets and the squiggly brackets.

2. Install the extension package from the More Actions context menu and specify the package path in your local file system.

3. Try to use your extension's feature in ZStudio. Extensions installed from VSIX will be listed under Installed and you can directly uninstalled it at any time. This also need to reload the current window.