Project File

Configure your LVGL Pro project with project.xml — set the LVGL version, exported code name, and the display targets used to preview screens.

project.xml is the top-level configuration file of an LVGL Pro project. It is read by the Editor, by the CLI, and by the runtime XML loader to learn the target LVGL version, the exported code's name, and the display configurations used to render screens in the preview.

project.xml lives next to globals.xml at the root of the project folder.

Recommended Project Layout

LVGL Pro doesn't enforce a folder structure, but the Editor, the tutorials, and the example projects all follow the same convention. Sticking to it keeps src_path references short and makes generated code predictable.

my_project/
├── project.xml          ← target/display configuration (this file)
├── globals.xml          ← shared fonts, images, subjects, consts, styles
├── translations.xml     ← optional, multi-language strings
├── fonts/               ← .ttf / .bin source files referenced by globals.xml
├── images/              ← .png assets referenced by globals.xml
├── widgets/             ← custom <widget> XMLs (one file per widget)
├── components/          ← reusable <component> XMLs (one file per component)
├── screens/             ← <screen> XMLs (one file per screen)
└── custom_data/         ← optional, arbitrary files copied into the Editor preview

The three XML files (project.xml, globals.xml, translations.xml) sit at the project root; the sub-folders hold everything else. Any of the sub-folders can be omitted if the project doesn't use that category.

Any files placed in a custom_data/ folder are copied into the Editor preview as-is. This is useful for shipping arbitrary application or test data (e.g. a JSON fixture or a data file read by a widget at runtime) alongside the UI.

Minimal Example

The simplest valid project file declares a name, the LVGL version, and at least one <target> with a <display>:

xml

<project name="ui" lvgl_version="9.5.0">
    <targets>
        <target name="target1">
            <display width="800" height="480"/>
        </target>
    </targets>
</project>

This is enough for the Editor to load the project with a given resolution. However, project.xml supports a whole lot of useful features. Keep reading to learn them all.

Multiple Targets

To preview Screens at multiple resolutions of real hardware, declare multiple <target> elements inside <targets>. Each target contains a <display> describing the screen size.

xml

<project name="ui" lvgl_version="9.5.0">
    <targets>
        <target name="large">
            <display width="800" height="480"/>
        </target>
        <target name="small">
            <display width="480" height="320"/>
        </target>
    </targets>
</project>

When a Screen is open in the Editor, the Preview panel shows one entry per <target>. This is also how the Editor knows how to size a Screen's <view>.

It's also possible to conditionally use assets, styles or even views based on selected target. It's a great way to manage assets and the appearance of components separately for different targets. Learn more at Targets

Theme

In project.xml you can also select the LVGL Theme you would like to use:

Simple: minimal styles for easy customization
Default: a good looking theme to quickly get started

TODO add images

To set a theme use <project theme="simple"> or <project theme="default">. If the theme is not set, default will be used.

Including Other Projects

A project can include other projects — for example a shared component library, or a common folder used by several projects. Declare them with a <folders> element in project.xml:

xml

<project name="ui" lvgl_version="9.5.0">
    <folders>
        <!-- Specifying root project is optional, but allows for controlling the precedence of globals -->
        <folder path="."/>
        <folder path="./lib"/>
        <folder path="../common"/>
    </folders>
    ...
</project>

Each <folder path="…"> points at another project folder (i.e. a folder containing its own project.xml/globals.xml). Its widgets, components, and globals become available to the including project.

Included projects may themselves declare <folders> to include further projects, but those nested inclusions are ignored — this feature is only one level deep. If root project A includes project B, and B includes project C, C is skipped and B will likely not function correctly.

Breaking change: existing projects that use a component library must be updated to include it explicitly with a <folder path="./lib"/> entry (adjusted to the library's actual path).

Relation to Other Files

globals.xml — Defines project-wide fonts, images, subjects, constants, and shared styles. See Introduction.
Screens — Use the targets declared here to choose a preview resolution. See Screens.
Code export — The name attribute controls the exported project name and init function. See Using Exported C Code.