Kanzi 4.1.1 migration guide

Use this migration guide to update Kanzi applications from Kanzi 4.1.0 to Kanzi 4.1.1.

Changes to the kzb file format version

The kzb file format version changes from 45.0 to 45.1. Export your project again with this version of Kanzi Studio. Kanzi loads only the exact format version that it expects, so a kzb file that an earlier version exported does not load.

Kanzi Studio moves referenced projects out of another project’s directory

When you open a project in Kanzi Studio 4.1.1, Kanzi Studio looks at every project it reaches through project references and moves any project stored inside another one’s directory out to a sibling directory. This is a one-time change to the directory layout on disk, it happens the first time you open the project, and you cannot undo it. Kanzi Studio does not open the project unless you let it move the directories. The exception is a project stored inside a directory of a project it references: Kanzi Studio cannot move either one, so it leaves that nesting in place and writes a warning to the log. It still moves every other nested project that it finds.

For example, Kanzi Studio turns this layout:

MyApplication/
   Tool_project/
      MyApplication.proj.kzm
      SharedAssets/
         SharedAssets.proj.kzm

into this one:

MyApplication/
   Tool_project/
      MyApplication.proj.kzm
   SharedAssets/
      SharedAssets.proj.kzm

Kanzi Studio updates the paths that it owns: project and kzb references, Kanzi Engine plugin paths, the Binary Export Directory, Application Export Directory, and Preview Working Directory settings, the Application Root Directory and APK Path build configuration settings, and the path properties that Kanzi Studio plugins add.

Two of those it leaves alone:

  • A setting whose value is a macro, such as <ProjectDirectory>, so that the setting keeps resolving on every machine. When such a setting pointed into a directory that moved, update it yourself.

  • A project in which you have unsaved changes. Kanzi Studio updates the paths of such a project without saving it, so that it does not save your changes for you, and writes a note to the Log window. Save that project to keep the updated paths.

The application code of a moved project needs no changes. Kanzi Studio moves the whole project directory as one unit, so the paths inside it, such as the ones in its CMake and Gradle configuration, keep resolving. Kanzi Studio does not touch the Visual Studio solution and project files, and CMake regenerates them with the new paths.

What breaks is the paths outside a moved project that point into it, because the depth of the directory changed. After the move, update:

  • Build scripts and pre-build events, such as the xcopy commands that copy application binaries from one project to another. These count directory levels, so a command written for a nested layout needs a different number of .. steps. The commands in Kanzi Studio solution structure already assume the layout Kanzi Studio enforces.

  • Continuous integration configuration.

  • .gitignore and the equivalent for your version control system, and any path stored in it.

  • Whatever loads the exported kzb file, when the Binary Export Directory of a project pointed into a moved directory. Kanzi Studio updates the setting itself, so the kzb file now lands in the new location.

Before you open an affected project, check its project file, and the project file of every project it references, out of version control. Kanzi Studio saves each project whose paths it updates, so it cancels the open when it finds a read-only project file. It also cancels the open when one of those projects is open in another Kanzi Studio instance.

When a project you reach is still in the kzproj format, Kanzi Studio asks to convert it to kzm before it saves it, which deletes the original kzproj file.

A command script that you run with KanziStudio.exe /Script moves the directories without asking, because the confirmation needs an interactive Kanzi Studio. When the script opens an affected project with the LoadProject command, open that project in Kanzi Studio once first, so that the move happens where you can confirm it. See Automating Kanzi Studio tasks.

To avoid the move, store referenced projects alongside the project that references them rather than inside its directory. Kanzi Studio 4.1.1 no longer lets you add a project as a reference when it is stored inside another project’s directory. See Where to store a referenced project.

See also

Kanzi 4.1.1 release notes

Known issues