gvsbuild

https://github.com/wingtk/gvsbuild
Admin
gvsbuild is a Python build tool that helps developers build a complete GTK library stack for Windows...
Tokens:9,479
Snippets:137
Trust Score:7.8
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install gvsbuild

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Install the tool using uv or clone the repository for a source-based installation.

```powershell
# Install using uv (recommended)
uv tool install gvsbuild

# Or clone and install from source
git clone https://github.com/wingtk/gvsbuild.git
cd gvsbuild
uv sync --no-dev
```

--------------------------------

### Install uv via WinGet

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Installs the uv Python package manager.

```PowerShell
winget install --id=astral-sh.uv  -e
```

--------------------------------

### Install Git via WinGet

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Installs Git for Windows using the WinGet package manager.

```PowerShell
winget install --id Git.Git -e --source winget
```

--------------------------------

### Build Python Bindings

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Build PyGObject and PyCairo wheels and install them into a virtual environment.

```powershell
# Build PyGObject with wheel generation
gvsbuild build --enable-gi --py-wheel gtk4 pygobject pycairo

# Install generated wheels in your virtualenv
pip install --force-reinstall (Resolve-Path C:\gtk-build\build\x64\release\pygobject\dist\PyGObject*.whl)
pip install --force-reinstall (Resolve-Path C:\gtk-build\build\x64\release\pycairo\dist\pycairo*.whl)
```

--------------------------------

### Install Generated Wheels

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Install the resulting PyGObject and pycairo wheels into the current Python virtual environment.

```PowerShell
pip install --force-reinstall (Resolve-Path C:\gtk-build\build\x64\release\pygobject\dist\PyGObject*.whl)
pip install --force-reinstall (Resolve-Path C:\gtk-build\build\x64\release\pycairo\dist\pycairo*.whl)
```

--------------------------------

### Example GTK Application in C

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

A basic GTK application source code for testing Visual Studio integration.

```C
#include <gtk/gtk.h>

static void activate_cb(GtkApplication *app) {
  GtkWidget *window = gtk_application_window_new(app);
  gtk_widget_set_visible(window, true);
}

int main(int argc, char **argv) {
  GtkApplication *app =
      gtk_application_new("org.app", G_APPLICATION_DEFAULT_FLAGS);
  g_signal_connect(app, "activate", G_CALLBACK(activate_cb), NULL);
  return g_application_run(G_APPLICATION(app), argc, argv);
}
```

--------------------------------

### Install PyGObject and PyCairo Wheels

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Installs the gvsbuild-generated wheels for PyGObject and PyCairo to resolve specific compatibility issues.

```PowerShell
pip install --force-reinstall (Resolve-Path C:\gtk\wheels\PyGObject*.whl)
pip install --force-reinstall (Resolve-Path C:\gtk\wheels\pycairo*.whl)
```

--------------------------------

### Install Visual Studio Build Tools via WinGet

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Installs the Visual Studio 2022 Build Tools with the necessary C++ workload.

```PowerShell
winget install Microsoft.VisualStudio.2022.BuildTools -e --source winget --silent --override "--wait --quiet --add ProductLang En-us --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
```

--------------------------------

### Install OpenSSL Dependencies

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Install the Visual C++ 2013 Redistributable Package via Chocolatey.

```PowerShell
choco install vcredist2013
```

--------------------------------

### Configure Environment Variables

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Set PATH, LIB, and INCLUDE variables to point to GTK installation directories.

```powershell
# Set environment for pre-built binaries (C:\gtk)
$env:Path = "C:\gtk\bin;" + $env:Path
$env:LIB = "C:\gtk\lib;" + $env:LIB
$env:INCLUDE = "C:\gtk\include;C:\gtk\include\cairo;C:\gtk\include\glib-2.0;C:\gtk\include\gobject-introspection-1.0;C:\gtk\lib\glib-2.0\include;" + $env:INCLUDE

# Set environment for custom build directory
$env:Path = "C:\gtk-build\gtk\x64\release\bin;" + $env:Path
$env:LIB = "C:\gtk-build\gtk\x64\release\lib;" + $env:LIB
$env:INCLUDE = "C:\gtk-build\gtk\x64\release\include;C:\gtk-build\gtk\x64\release\include\cairo;C:\gtk-build\gtk\x64\release\include\glib-2.0;C:\gtk-build\gtk\x64\release\include\gobject-introspection-1.0;C:\gtk-build\gtk\x64\release\lib\glib-2.0\include;" + $env:INCLUDE
```

--------------------------------

### Update GtkDoInstall in gtk-install.props

Source: https://github.com/wingtk/gvsbuild/blob/main/gvsbuild/patches/gtk2/mod.md

Commands to copy PDB files and libpixmap DLL to the installation directory.

```batch
copy "$(BinDir)\$(GtkDllPrefix)gdk$(GtkDllSuffix).pdb" $(CopyDir)\bin
copy "$(BinDir)\libpixmap.pdb" $(CopyDir)\bin
copy "$(BinDir)\libwimp.pdb" $(CopyDir)\bin
```

```batch
copy $(BinDir)\*.pdb $(CopyDir)\bin
```

```batch
copy "$(BinDir)\libpixmap.dll" $(CopyDir)\lib\gtk-$(ApiVersion)\$(GtkHost)\engines
```

--------------------------------

### Install MSYS2 via WinGet

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Installs the MSYS2 environment required for building GTK projects.

```PowerShell
winget install --id MSYS2.MSYS2 -e --source winget
```

--------------------------------

### Configure Visual Studio

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Specify the Visual Studio version, Windows SDK, or custom installation path for the build environment.

```powershell
# Use Visual Studio 2022 (default)
gvsbuild build --vs-ver 17 gtk4

# Use Visual Studio 2019
gvsbuild build --vs-ver 16 gtk4

# Specify Windows SDK version
gvsbuild build --win-sdk-ver 10.0.22621.0 gtk4

# Specify custom Visual Studio installation path
gvsbuild build --vs-install-path "C:\Program Files\Microsoft Visual Studio\2022\Professional" gtk4
```

--------------------------------

### GTK4 Application Example

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Basic C code for a GTK4 application and associated compiler/linker flags.

```c
// main.c - Basic GTK4 application
#include <gtk/gtk.h>

static void activate_cb(GtkApplication *app) {
    GtkWidget *window = gtk_application_window_new(app);
    gtk_widget_set_visible(window, true);
}

int main(int argc, char **argv) {
    GtkApplication *app =
        gtk_application_new("org.app", G_APPLICATION_DEFAULT_FLAGS);
    g_signal_connect(app, "activate", G_CALLBACK(activate_cb), NULL);
    return g_application_run(G_APPLICATION(app), argc, argv);
}
```

```powershell
# Get compiler flags for your Visual Studio project
pkg-config --cflags gtk4 --msvc-syntax

# Get linker flags for your Visual Studio project
pkg-config --libs gtk4 --msvc-syntax
```

--------------------------------

### Install Development Tools via Chocolatey

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Installs Git, MSYS2, Visual Studio 2022, and uv using Chocolatey in an administrator PowerShell terminal.

```PowerShell
choco install git
```

```PowerShell
choco install msys2
```

```PowerShell
choco install visualstudio2022-workload-vctools
```

```PowerShell
choco install uv
```

--------------------------------

### Install Chocolatey via PowerShell

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Requires an administrator PowerShell terminal.

```PowerShell
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
```

--------------------------------

### Configure GTK Environment Variables

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Sets the necessary Path, LIB, and INCLUDE environment variables for a GTK installation located at C:\gtk.

```PowerShell
$env:Path = "C:\gtk\bin;" + $env:Path
$env:LIB = "C:\gtk\lib;" + $env:LIB
$env:INCLUDE = "C:\gtk\include;C:\gtk\include\cairo;C:\gtk\include\glib-2.0;C:\gtk\include\gobject-introspection-1.0;C:\gtk\lib\glib-2.0\include;" + $env:INCLUDE
```

--------------------------------

### Update Path Variables in gtk-version-paths.props

Source: https://github.com/wingtk/gvsbuild/blob/main/gvsbuild/patches/gtk2/mod.md

Modifications to path definitions for Glib installation and DLL suffixes.

```xml
<GlibEtcInstallRoot>..\..\..\..\..\..\..\gtk\$(Platform)\$(Configuration)</GlibEtcInstallRoot>
```

```xml
<CopyDir>..\..\..\..\gtk-rel</CopyDir>
```

```xml
<GtkSeparateVSDllSuffix>-2.0</GtkSeparateVSDllSuffix>
```

--------------------------------

### Use Configuration Files

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Define build parameters in a file and execute the build using the @ prefix.

```text
--vs-ver
14
--win-sdk
8.1
--configuration
release
```

```text
gvsbuild build @vs2015-release.pro gtk3-full
```

--------------------------------

### Access Gvsbuild Help

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Display general or build-specific help information.

```text
gvsbuild --help
```

```text
gvsbuild build --help
```

--------------------------------

### Configuration File Usage

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Use a configuration file to specify build options.

```powershell
# Create a configuration file (vs2022-release.pro)
# Contents (one option per line):
# --vs-ver
# 17
# --win-sdk-ver
# 10.0.22621.0
# --configuration
# release

# Use configuration file with @ prefix
gvsbuild build @vs2022-release.pro gtk4
```

--------------------------------

### List Available Projects

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Display all projects, tools, and groups available for building.

```powershell
# List all available projects
gvsbuild list
```

--------------------------------

### Build GTK3

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Build the GTK3 stack with various platform and configuration settings.

```powershell
# Build GTK3 with default settings (x64, release)
gvsbuild build gtk3

# Build GTK3 for 32-bit Windows
gvsbuild build --platform x86 gtk3

# Build GTK3 with debug configuration
gvsbuild build --configuration debug gtk3

# Build GTK3 with debug symbols in release mode
gvsbuild build --configuration debug-optimized gtk3
```

--------------------------------

### List Projects with gvsbuild

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Commands to display project information, dependencies, and filter by type.

```bash
gvsbuild list --json

gvsbuild list --projects-names gtk4 --show-deps

gvsbuild list --project-type project
```

--------------------------------

### Build OpenSSL

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Execute the build command for the OpenSSL package.

```text
gvsbuild build openssl
```

--------------------------------

### Build PyGObject with Gvsbuild

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Execute the build command with GI and wheel support enabled.

```PowerShell
gvsbuild build --enable-gi --py-wheel gtk4 pygobject
```

--------------------------------

### Clean and Rebuild Options

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Manage build caching, cleaning, and incremental build behavior.

```powershell
# Clean project before building
gvsbuild build --clean gtk4

# Start completely from scratch (removes all build artifacts)
gvsbuild build --from-scratch gtk4

# Start from scratch but keep downloaded tools
gvsbuild build --from-scratch --keep-tools gtk4

# Fast build - skip already built projects
gvsbuild build --fast-build gtk4

# Continue building even if some projects fail
gvsbuild build --keep-going all
```

--------------------------------

### Build GTK with gvsbuild

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Commands to build specific versions of GTK.

```PowerShell
uv run gvsbuild build gtk3
```

```PowerShell
uv run gvsbuild build gtk4
```

--------------------------------

### Build FFmpeg

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Build FFmpeg with optional GPL-licensed components.

```powershell
# Build FFmpeg (LGPL only)
gvsbuild build ffmpeg

# Build FFmpeg with GPL libraries enabled
gvsbuild build --ffmpeg-enable-gpl ffmpeg
```

--------------------------------

### Configure Ninja and MSBuild

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Pass custom flags and options to the underlying build systems.

```powershell
# Limit parallel jobs in ninja (useful for low memory systems)
gvsbuild build --ninja-opts -j2 gtk4

# Pass verbose flag to ninja
gvsbuild build --ninja-opts --verbose gtk4

# Pass custom MSBuild options
gvsbuild build --msbuild-opts "/m:4" gtk4

# Pass extra options to specific projects
gvsbuild build --extra-opts "glib:-Dselinux=disabled;-Dlibmount=disabled" gtk4
```

--------------------------------

### Analyze Project Dependencies

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Generate a dependency graph file for the project structure.

```text
gvsbuild deps --graph --gv-file test.gv
```

--------------------------------

### Configure Environment for PyGObject

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Set the necessary LIB and INCLUDE environment variables to point to the GTK build directories.

```PowerShell
$env:LIB = "C:\gtk-build\gtk\x64\release\lib;" + $env:LIB
$env:INCLUDE = "C:\gtk-build\gtk\x64\release\include;C:\gtk-build\gtk\x64\release\include\cairo;C:\gtk-build\gtk\x64\release\include\glib-2.0;C:\gtk-build\gtk\x64\release\include\gobject-introspection-1.0;C:\gtk-build\gtk\x64\release\lib\glib-2.0\include;" + $env:INCLUDE
```

--------------------------------

### Set MSVC project library paths and dependencies

Source: https://github.com/wingtk/gvsbuild/blob/main/gvsbuild/patches/libssh/mod.md

Configure the library search path and link the necessary static libraries in the MSVC project settings.

```text
C:\gtk-build\gtk\Win32\release\lib;
```

```text
libeay32.lib;ssleay32.lib;zlib1.lib;
```

--------------------------------

### Configure Build Directories

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Customize paths for build artifacts, source downloads, tools, and MSYS2.

```powershell
# Use custom build directory
gvsbuild build --build-dir D:\gtk-build gtk4

# Specify custom archives download directory
gvsbuild build --archives-download-dir D:\sources gtk4

# Specify custom tools directory
gvsbuild build --tools-root-dir D:\tools gtk4

# Specify custom MSYS2 installation
gvsbuild build --msys-dir C:\msys64 gtk4
```

--------------------------------

### Build GTK4

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Build the GTK4 toolkit with support for optional features like Adwaita icons, GObject introspection, and Python wheels.

```powershell
# Build GTK4
gvsbuild build gtk4

# Build GTK4 with Adwaita icons (recommended for apps)
gvsbuild build gtk4 adwaita-icon-theme

# Build GTK4 with GObject introspection support
gvsbuild build --enable-gi gtk4

# Build GTK4 with Python wheel generation for PyGObject
gvsbuild build --enable-gi --py-wheel gtk4 pygobject
```

--------------------------------

### Configure Documentation Features

Source: https://github.com/wingtk/gvsbuild/blob/main/gvsbuild/patches/gperf/meson_options.txt

Options for controlling documentation generation. Set to 'disabled' to skip, 'auto' to attempt generation if dependencies are met, or specify other values as needed.

```gvsbuild
option('docs', type: 'feature', value: 'disabled')
```

```gvsbuild
option('doc-ps', type: 'feature', value: 'disabled')
```

```gvsbuild
option('doc-dvi', type: 'feature', value: 'disabled')
```

```gvsbuild
option('doc-man', type: 'feature', value: 'auto')
```

```gvsbuild
option('doc-pdf', type: 'feature', value: 'auto')
```

```gvsbuild
option('doc-info', type: 'feature', value: 'auto',)
```

```gvsbuild
option('doc-html', type: 'feature', value: 'auto')
```

```gvsbuild
option('doc-examples', type: 'feature', value: 'auto')
```

--------------------------------

### Logging and Debugging Options

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Control build output verbosity and log file management.

```powershell
# Enable verbose output
gvsbuild build --verbose gtk4

# Enable debug messages
gvsbuild build --debug gtk4

# Capture build output to log files
gvsbuild build --capture-out gtk4

# Print captured output to console as well
gvsbuild build --capture-out --print-out gtk4

# Use single log file with timestamp
gvsbuild build --log-single gtk4

# Limit log file size (in KB) before rotation
gvsbuild build --log-size 10240 gtk4
```

--------------------------------

### Generate Dependency Graphs

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Visualize project dependencies in text or Graphviz format.

```powershell
# Print dependency tree as text
gvsbuild deps

# Print flattened dependencies
gvsbuild deps --flatten

# Generate Graphviz dependency graph
gvsbuild deps --graph --gv-file dependencies.gv

# Include tools in the graph
gvsbuild deps --graph --add-tools --gv-file full-deps.gv

# Invert dependency direction (show what depends on what)
gvsbuild deps --graph --invert --gv-file reverse-deps.gv

# Skip specific projects from graph
gvsbuild deps --graph --skip gtk2 --skip gtk3 --gv-file gtk4-only.gv
```

--------------------------------

### Build Multiple Projects

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Build specific libraries, groups, or exclude projects from the build process.

```powershell
# Build specific libraries
gvsbuild build libpng libffi zlib

# Build only a project without dependencies
gvsbuild build --no-deps glib

# Build everything except specific projects
gvsbuild build --skip gtk4 --skip pycairo all

# Build the full GTK3 stack with extras
gvsbuild build gtk3-full

# Build all GStreamer plugins
gvsbuild build gstreamer-all
```

--------------------------------

### Define a Library Project with Meson in gvsbuild

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Use this class to define a library project that uses the Meson build system and is distributed as a tarball. Specify dependencies, patches, and Meson build parameters.

```python
from gvsbuild.utils.base_builders import Meson
from gvsbuild.utils.base_expanders import Tarball
from gvsbuild.utils.base_project import Project, project_add

@project_add
class MyLibrary(Tarball, Meson):
    def __init__(self):
        Project.__init(
            self,
            "mylibrary",
            version="1.0.0",
            archive_url="https://example.com/mylibrary-{version}.tar.xz",
            hash="sha256hashhere",
            dependencies=["glib", "cairo"],
            patches=["fix-windows-build.patch"],
        )
        self.add_param("-Dtests=false")
        self.add_param("-Ddocumentation=false")

    def build(self):
        Meson.build(self)
        self.install(r".\COPYING share\doc\mylibrary")
```

--------------------------------

### Create ZIP Archives

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Generate distributable ZIP archives for built projects.

```powershell
# Build and create ZIP archives
gvsbuild build --make-zip gtk4

# Continue adding to existing ZIP (incremental)
gvsbuild build --make-zip --zip-continue gtk4 adwaita-icon-theme
```

--------------------------------

### Build OpenSSL

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Build OpenSSL with optional FIPS module support.

```powershell
# Build OpenSSL (requires vcredist2013)
choco install vcredist2013
gvsbuild build openssl

# Build OpenSSL with FIPS validated cryptographic module
gvsbuild build --enable-fips openssl
```

--------------------------------

### Check for Outdated Projects

Source: https://context7.com/wingtk/gvsbuild/llms.txt

Scan for newer upstream versions. Requires the lastversion package.

```powershell
# Check all projects for updates (requires lastversion package)
gvsbuild outdated

# Install required dependency first
pip install lastversion
gvsbuild outdated
```

--------------------------------

### Configure MSYS2 Environment

Source: https://github.com/wingtk/gvsbuild/blob/main/README.md

Prioritize the MSYS2 environment path to resolve conflicts on GitHub Windows runners.

```PowerShell
$env:Path = "C:\msys64\usr\bin;$env:Path"
```

--------------------------------

### Configure libssh CMake variables for Win32

Source: https://github.com/wingtk/gvsbuild/blob/main/gvsbuild/patches/libssh/mod.md

Set these variables in cmake-gui to define dependency paths for Zlib and OpenSSL when building for Win32.

```text
ZLIB_INCLUDE_DIR=C:\gtk-build\gtk\Win32\release\include
ZLIB_LIBRARY=C:\gtk-build\gtk\Win32\release\lib
OPENSSL_INCLUDE_DIR=C:\gtk-build\gtk\Win32\release\include
OPENSSL_ROOT_DIR=C:\gtk-build\gtk\Win32\release\x64
SSL_EAY_DEBUG=C:\gtk-build\gtk\Win32\release\lib\ssleay32.lib
SSL_EAY_RELEASE=C:\gtk-build\gtk\Win32\release\lib\ssleay32.lib
LIB_EAY_DEBUG=C:\gtk-build\gtk\Win32\release\lib\libeay32.lib
LIB_EAY_RELEASE=C:\gtk-build\gtk\Win32\releaselib\libeay32.lib
```

--------------------------------

### Configure Tests Feature

Source: https://github.com/wingtk/gvsbuild/blob/main/gvsbuild/patches/gperf/meson_options.txt

Set the 'tests' feature to 'disabled' to prevent test execution during the build process. This is useful for production builds or when tests are not required.

```gvsbuild
option('tests', type: 'feature', value: 'disabled')
```
Tokens:
Raw