Apple.Pkl.MSBuild 0.30.0

Apple.Pkl.MSBuild

MSBuild integration package for Apple's Pkl configuration language, providing seamless compilation of Pkl files as part of your .NET build process.

Overview

Apple.Pkl.MSBuild enables you to compile Pkl configuration files directly within your .NET projects using MSBuild. It automatically handles downloading platform-specific Pkl binaries, compiling Pkl files to various output formats, and integrating the compiled configurations into your build and publish workflows.

Features

• 🚀 Automatic Compilation - Compile Pkl files during MSBuild execution
• 📦 Multiple Output Formats - Support for JSON, YAML, XML, Properties, and more
• 🔧 MSBuild Integration - Native MSBuild tasks and targets
• 🌐 Cross-Platform - Works on Windows, Linux, and macOS
• 📁 Flexible Output - Flat or recursive directory structures
• 🛠️ Tool Management - Automatic Pkl CLI binary management
• 📤 Publish Integration - Compiled files included in publish output
• ⚡ Incremental Builds - Only recompiles when source files change

Installation

Add the package to your project:

<PackageReference Include="Apple.Pkl.MSBuild" Version="0.29.1" />

Optionally either set the PklPath variable to the Pkl binary path or reference the platform specific Apple.Pkl.Cli.*

<PackageReference Include="Apple.Pkl.Cli.win-x64" Version="0.29.1" />

Quick Start

1. Add Pkl Files to Your Project

Create a Pkl configuration file (e.g., config.pkl):

// config.pkl
appName = "MyApplication" 
version = "1.0.0"
database {
  host = "localhost"
  port = 5432
  connectionString = "Host=\(host);Port=\(port);Database=myapp"
}
features {
  enableLogging = true
  maxRetries = 3
}

2. Configure Compilation

Add the Pkl file to your project file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Apple.Pkl.MSBuild.win-x64" Version="0.29.1" />
    <PackageReference Include="Apple.Pkl.MSBuild" Version="0.29.1" />
  </ItemGroup>
  
  <ItemGroup>
    <Pkl Include="config.pkl" Format="json" />
  </ItemGroup>
</Project>

3. Build Your Project

When you build your project, config.pkl will be compiled to config.json in your output directory:

dotnet build

Output (bin/Debug/net8.0/config.json):

{
  "appName": "MyApplication",
  "version": "1.0.0",
  "database": {
    "host": "localhost",
    "port": 5432,
    "connectionString": "Host=localhost;Port=5432;Database=myapp"
  },
  "features": {
    "enableLogging": true,
    "maxRetries": 3
  }
}

Pkl Item Configuration

Basic Syntax

<ItemGroup>
  <Pkl Include="path/to/file.pkl" Format="json" />
</ItemGroup>

Item Metadata

Multiple Files Example

<ItemGroup>
  <Pkl Include="configs/app.pkl" Format="json" />
  <Pkl Include="configs/database.pkl" Format="yaml" />
  <Pkl Include="configs/logging.pkl" Format="xml" />
  <Pkl Include="settings/*.pkl" Format="properties" />
</ItemGroup>

Supported Output Formats

MSBuild Properties

Core Properties

Output Styles

Flat Output (PklOutputStyle=Flat)

All compiled files are placed directly in the output directory:

<PropertyGroup>
  <PklOutputStyle>Flat</PklOutputStyle>
</PropertyGroup>

Directory structure:

bin/Debug/net8.0/
├── MyApp.exe
├── config.json
├── database.yaml
└── logging.xml

Recursive Output (PklOutputStyle=Recursive)

Maintains the source directory structure in the output:

<PropertyGroup>
  <PklOutputStyle>Recursive</PklOutputStyle>
</PropertyGroup>

Directory structure:

bin/Debug/net8.0/
├── MyApp.exe
└── configs/
    ├── app.json
    ├── database.yaml
    └── sub/
        └── logging.xml

Custom Output Directory

<PropertyGroup>
  <PklOutputPath>$(OutputPath)configurations\</PklOutputPath>
</PropertyGroup>

Custom Build Timing

<PropertyGroup>
  
  <PklCompileAfterTargets>BeforeBuild</PklCompileAfterTargets>
  
  
  <PklCompileAfterTargets>PrepareForPublish</PklCompileAfterTargets>
</PropertyGroup>

Publish Integration

Compiled Pkl files are automatically included in publish operations:

dotnet publish

The published output will include all compiled configuration files according to your PklOutputStyle setting.