rootdarkarchon/DalamudPackager

#+title: DalamudPackager
#+options: ^:{}
#+options: toc:nil

This is an MSBuild task that is designed to simplify creating plugins
for [[https://github.com/goatcorp/Dalamud][Dalamud]].

Install the NuGet package DalamudPackager. When you build in release
mode, a folder will be placed in your output directory containing your
plugin manifest and latest.zip.

• Table of contents :TOC:

• [[#configuration][Configuration]]
• [[#manifest-generation][Manifest generation]]
• [[#yaml-manifests][YAML manifests]]
• [[#zip-file-generation][.zip file generation]]
• [[#task-attributes][Task attributes]]

• Configuration

If you need to additionally configure the task, create a file called
DalamudPackager.targets in your project and use the template below.

#+begin_src xml

#+end_src

• Manifest generation

DalamudPackager reduces the amount of keys you need to include in your
manifest, filling in the rest from sane defaults or your assembly. You
can, of course, specify everything manually.

#+begin_src json5
{
"Name": "Test Plugin",
"Author": "You",
"Description": "This is a test plugin",
"RepoUrl": "https://example.com/"
}
#+end_src

Notice how keys like AssemblyVersion and DalamudApiLevel are
missing. You can include these if you'd like, but DalamudPackager will
automatically do it for you when you build your project. If you build
a project with this manifest in Release mode, you will find the
following JSON file in your output directory.

#+begin_src json5
{
"Author": "You",
"Name": "Test Plugin",
// this will be set to your AssemblyName automatically
"InternalName": "TestPlugin",
// this will be set to your assembly's version automatically
"AssemblyVersion": "1.0.0.0",
"Description": "This is a test plugin - this first line is a summary.\n\nDown here is a more detailed explanation of what the plugin\ndoes, manually wrapped to make sure it stays visible in the\ninstaller.",
// this will be set to "any" automatically
"ApplicableVersion": "any",
"RepoUrl": "https://example.com/",
// this will be set to 2 automatically
"DalamudApiLevel": 2,
// this will be set to 0 automatically
"LoadPriority": 0
}
#+end_src

• YAML manifests

In addition, DalamudPackager allows you to use YAML, a more
human-friendly format, for your manifest instead of JSON. YAML uses
snake_case for keys instead of PascalCase like JSON. All the
features of DalamudPackager work with YAML manifests. Just end your
manifest's file name with .yaml instead of .json to make use of
it.

#+begin_src yaml
name: Test Plugin
author: You
description: |-
This is a test plugin - this first line is a summary.

Down here is a more detailed explanation of what the plugin
does, manually wrapped to make sure it stays visible in the
installer.
repo_url: https://example.com/
#+end_src

• .zip file generation

DalamudPackager will also create a folder with latest.zip for you if
MakeZip is true. Check your output directory for a folder with the
name of your assembly. Inside will be your manifest and latest.zip,
ready for distribution or PRs.

Note that the entire contents of your output directory will be zipped
by default. Either turn off copy local for Dalamud references, set up
a task to clean your output directory, or use Exclude or Include
if you want to change this.

• Task attributes

| Attribute | Description | Required | Default |
|---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+-----------------------------------|
| ProjectDir | This is the path where your csproj is located. You must set this to $(ProjectDir). | Yes | /None/ - set to $(ProjectDir) |
| OutputPath | This is the path that your assemblies are output to after build. You must set this to $(OutputPath). | Yes | /None/ - set to $(OutputPath) |
| AssemblyName | This is the name of the assembly that Dalamud will be loading. You used to need to specify this in your manifest as InternalName. | Yes | /None/ - set to $(AssemblyName) |
| ManifestType | You can choose between auto, json, and yaml for your manifest file. auto will use json first, then fall back on yaml. | No | auto |
| VersionComponents | How many components of the assembly's version to include in the generated manifest. If you use semantic versioning, set this to 3. | No | 4 |
| MakeZip | If this is true, a folder will be created in your OutputPath that contains your generated manifest and latest.zip, reading for PRing. | No | false |
| Exclude | Files to exclude from the zip if MakeZip is true. Mutually exclusive with Include. Files should be separated by a semicolon (;) and be relative to OutputPath. Files do not need to exist. | No | /None/ |
| Include | Files to include in the zip if MakeZip is true. Mutually exclusive with Exclude. Files should be separated by a semicolon (;) and be relative to OutputPath. Files must exist. | No | /None/ |