Craftitude repository documentation.

CraftitudeDocumentation.md

Craftitude Repository Documentation

Gist Draft Mar 28 2013, Version 0.2d by Icedream (Carl Kittelberger)

Filesystem Tree

[DIR] repositoryname
	[DIR] <minecraft version>
  		[FILE] packages.yml*
		[FILE] packages.yml?since=<date>*
		[FILE] packages.yml.gz*
		[FILE] packages.yml.gz?since=<date>*
		[DIR] packages
			[DIR] <platform-dependent package name>
				[DIR] <version>
					[FILE] metadata.yml
					[DIR] <platform: windows/macosx/solaris/linux>
						[FILE] install
						[FILE] uninstall
						[FILE] source
				[DIR] <version>
					[FILE] metadata.yml
					[DIR] <platform>
						[FILE] install
						[FILE] uninstall
						[FILE] source
				...
			[DIR] <platform-independent package name>
				[DIR] <version>
					[FILE] metadata
					[FILE] install
					[FILE] uninstall
					[FILE] source
				[DIR] <version>
					[FILE] metadata
					[FILE] install
					[FILE] uninstall
					[FILE] source
				...
			...
	...
...

* This file is recommended to be generated dynamically either by cron (every day
  at least) or per request (using some weak sort of caching at least) from other
  available data in the repository directory.

Distribution Packages file (packages.yml)

The packages.yml file is a YAML-compatible file. It's contents are:

• All packages in the current repository o Package metadata o Available version IDs o Reference to most current version ID

Note: packages.yml.gz is a GZIP-compressed copy or mirror of this file.

Typical plain content:

Package1:
  Metadata:
  <Version 1>:
    # Metadata, look in the Package Metadata file section for the contents
  <Version 2>:
    # Metadata, look in the Package Metadata file section for the contents
  ...
  Current Version: Current version ID here
Package2:
  ...

Recommendation: Generate this file dynamically when needed (by request) or in a periodic time interval (by cron) from the available Package Metadata files.

Distribution Packages Patch file (packages.yml?since=...)

This file can be generated by a script sorting out only the updated packages since a specific date and only transfer those to the client. This is more efficient than downloading the full contents every time something changes in general.

Note: packages.yml.gz?since=... is a GZIP-compressed copy or mirror of this file.

The contents and the typical plain content are equal to those of the complete Distribution Packages file, though the file will only contain packages updated since the specified date.

In case the server doesn't support the since parameter and therefore can't serve updates as patches, the client will just use a fallback and compare all cached entries with those which the server sends (which is every package with every metadata as it accesses the full packages.yml).

Parameters:

• "since": Specifies the date until when packages should be seen as "old" and should not be transferred anymore. The date should be ideally formatted after ISO 8601 or - if the repository server/script supports it - some shorter variant of it.

Recommendation: Generate this file dynamically when needed (by request) or in a periodic time interval (by cron) from the available Package Metadata files.

Package Metadata file (metadata.yml)

This file must contain all essential data to identify the package and its properties. Contents are as following:

• "ID" (optional): The ID of the package. If not used, will be automatically defaulted to whatever the client finds first, the ID in one of the Repository Packages file variants or in the URL.
• "Description": The description of what the package contains, does or implies. Should usually not exceed 2048 chars.
• "Maintainers": A list of package maintainers.
• "Developers": A list of developers of the files within the package.
• "License": Can be either a url to, the name of or the text of a license, or a combination of them, delimited by a semicolon and a space ("; ").
• "Dependencies" (optional): A list of IDs of all packages on which the current package's version depends on.
• "Platform dependency": Indicates whether the package should serve different files seperated for each operating system platform. More about platform-dependent packages in the respective section Platform-dependent packages. Accepted values are "True" and "False".

Example:

Description: |
  This is a simple multiline description.
  
  It even supports empty lines.
Maintainers:
  - Icedream
  - Railcrafti
Developers:
  - Icedream
License: GNU General Public License Version 3; http://opensource.org/licenses/GPL-3.0
Platform dependency: False

Package Install (install) / Uninstall (uninstall) Instruction files

PII/PUI files tell the client how to handle the contents of a package to in- stall or uninstall it by giving it instructions. Those instructions are given in form of a LUA script. Following functions are available besides the basic LUA features available in each standard LUA script:

• SetMetaInfIgnore(value) Manipulates behaviour for META-INF data in JAR source archives. can be true or false, where true forces META-INF data to be handles as normal directories/files and false forces META-INF data to be completely ignored.
• UnpackAllFromSource(targetdir) Unpacks all files from the source archive into .
• UnpackAllFromSource(targetdir, filter) Unpacks all files from the source archive matching the file filter into . The filter has the same form as the glob() function in PHP. Example: "." for all files or "*.class" for only files which end with ".class".
• InjectAllFromSource(targetfile) Injects all files from the source archive into the archive at .
• InjectAllFromSource(targetfile, filter) Injects all files from the source archive matching the glob filter into the archive at .
• DeleteFile(targetfile) Deletes .
• DeleteDir(targetdir) Deletes and all its subdirectories.
• Move(source, target) Moves a directory or a file from to . Can be also used as an explicit absolute path rename.
• Rename [not implemented yet]
• GetPackageMetadata(propertyname) Gets the currently processed package's version's metadata property 's value. The return type is the same one served by the YAML data of the package metadata.
• GetPackageVersion() Gets the currently processed package's version.
• GetBaseDir() [obsolete] Gets the base target directory into which the client installs all files.

Simple example of a typical fully working install instruction:

UnpackAllFromSource("my_mod_folder") -- unpack all source files into "<basedir>\my_mod_folder\"

Simple example of a typical fully working uninstall instruction:

DeleteFolder("my_mod_folder") -- delete all folders from the "<basedir>\my_mod_folder\"

Security measurements:

• You can not do file operations outside the base target directory (the directory to which the client installs all files of all packages).