Package-info.xml

From SMFMods

Jump to: navigation, search
[–] Category:Packages
Modification.xml
Package-info.xml


Contents

[edit] Introduction

package-info.xml is one of the main files inside an SMF package. It details exactly what the SMF mod does when it installs. In its simplest form, a package-info.xml file looks like: 

<?xml version="1.0"?>
<?xml-stylesheet href="package-info.xsl" type="text/xsl"?>
<!DOCTYPE package-info SYSTEM "http://www.simplemachines.org/xml/package-info">
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
	ATTENTION: If you are trying to install this manually, you should try
	the package manager.  If it will not work for you, please take a look
	at the following for information on this format:
		http://mods.simplemachines.org/docs/manual-install.php
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
<package-info xmlns="http://www.simplemachines.org/xml/package-info" xmlns:smf="http://www.simplemachines.org/">
	<id>Daniel15:TestCase2</id>
	<name>Test Case for Package Parsing utilities</name>
	<version>1.1</version>
	<type>modification</type>
 
	<install for="1.1, 1.1.1-1.1.99">
		<readme>readme.txt</readme>
		<code>installScript.php</code>
 
		<require-dir name="shop" destination="$sourcedir" />
		<require-file name="Shop.english.php" destination="$languagedir" />
		<require-file name="ShopAdmin.template.php" destination="$themedir" />
		<require-file name="Shop.template.php" destination="$themedir" />
 
		<modification format="xml" type="file">install_SMF1-1.xml</modification>
	</install>
 
	<uninstall for="1.1, 1.1.1-1.1.99">
		<code>uninstallScript.php</code>
		<remove-dir name="$sourcedir/shop" />
		<remove-file name="$languagedir/Shop.english.php" />
		<remove-file name="$themedir/ShopAdmin.template.php" />
		<remove-file name="$themedir/Shop.template.php" />
 
		<modification type="file" reverse="true">install_SMF1-1.xml</modification>
	</uninstall>
 
 
</package-info>

This is just an example, package-info.xml files can vary quite a bit.

[edit] Basic sections

Every package-info.xml file has the following tags:

  • id — An ID for the package. This must be unique, and should be formatted like Your SMF username:PackageName (where "Your SMF username" is your username on the simplemachines.org Community Forum, and PackageName is the name of the mod, without any spaces. For example, Daniel15:TestCase2
  • name — The name of the mod. This is what is displayed in the Package Manager. For example, Test Case for Package Parsing utilities
  • version — Version of the mod. This should be kept numeric, as this makes it easier for SMF to tell which version is newer. For example, 1.1. Note: When you release a new version of your mod, the ID should stay the same, and only the version should change!
  • type — The type of modification package. This should be one of modification, avatar or language.

[edit] Install

Each package-info.xml file should have at least one install section. The "for" attribute defines which SMF versions this install section will be used for. It can be a comma-separated list of version numbers (eg. 1.1.1, 1.1.2, 1.1.3), a hyphen-separated range (eg. 1.1.1-1.1.3), or a mix of both (eg. 1.1, 1.1.1-1.1.3). If no "for" attribute is specified, this section will be used for any other SMF versions (any versions not explicitly matched by another install section).

As an example: 

<install for="1.1, 1.1.1-1.1.99">
	<!-- Contents ommited for clarity -->
</install>
 
<install>
	<!-- Contents ommited for clarity -->
</install>

If the user was using SMF 1.1, or any version between SMF 1.1.1 to 1.1.99, the first install section will be used. Otherwise, if they're using a different version (eg. SMF 1.0 or SMF 2.0), the second section will be used.

[edit] Uninstall

Uninstall sections are similar to install sections.

Example: 

<uninstall for="1.1, 1.1.1-1.1.99">
	<!-- Contents omitted for clarity -->
</uninstall>
 
<uninstall>
	<!-- Contents omitted for clarity -->
</uninstall>

[edit] Upgrade

Upgrade sections are similar to install and uninstall sections, with one significant difference — They also specify an old version of the mod (with the "from" attribute). As with install and uninstall sections, the "for" attribute is optional.

An example: 

<upgrade from="1.1">
	<readme>readme_upgrade.txt</readme>
	<code>upgradeScript.php</code>
 
	<require-file name="Shop.template.php" destination="$themedir" />	
	<create-dir name="test" destination="$boarddir" />
	<move-file name="changelog.txt" from="$boarddir" destination="$sourcedir" />
 
	<modification format="xml" type="file">upgrade_1-0_SMF1.1.xml</modification>
</upgrade>
 
<upgrade from="1.0" for="1.1, 1.1.1-1.1.99">
	<readme>readme_upgrade.txt</readme>
	<code>upgradeScript.php</code>
 
	<require-file name="Shop.template.php" destination="$themedir" />	
	<create-dir name="test" destination="$boarddir" />
	<move-file name="changelog.txt" from="$boarddir" destination="$sourcedir" />
 
	<modification format="xml" type="file">upgrade_1-0_SMF1.1.xml</modification>
</upgrade>
 
<upgrade from="1.0">
	<readme>readme_upgrade.txt</readme>
	<code>upgradeScript.php</code>
 
	<require-file name="Shop.template.php" destination="$themedir" />	
	<create-dir name="test" destination="$boarddir" />
	<move-file name="changelog.txt" from="$boarddir" destination="$sourcedir" />
 
	<modification format="xml" type="file">upgrade_1-0_SMF1.1.xml</modification>
</upgrade>

With the example above, if the user had version 1.1 of the mod installed, the first section would be used. If the user had version 1.0 of the mod installed on SMF 1.1, the second section would be used. Finally, if they had version 1.0 of the mod installed on anything except for SMF 1.1, the third section would be used.

[edit] Inside the sections themselves

Inside the install, uninstall and upgrade sections, a number of elements may be used. These are:

[edit] General elements

  • readme — A readme to use.
    Attributes:
    • parsebbc — If set to "yes", BBCode will be parsed in the readme you may use BBCode in it).
    • type — If set to "inline", readme is assumed to be inline: 
      <readme type="inline">Your readme goes here!</readme>
      . Otherwise, it is assumed to be a file name: 
      <readme>readme.txt</readme>
  • code — Name of a PHP script to run during installation. Usually, this script will do things like add settings to the database, etc.
  • modification — Name of a Modification XML File to use. This can be used more than once within the one section.
    • reverse — If set to true, the changes in the modification will be reversed (effectively undoing the mod). This is often used in uninstall sections, so you don't need a separate uninstall modification file.

[edit] Installed files

  • require-file — This is the one of the most common elements. It is used when you want to copy a file from the package archive into the SMF directory. Attributes:
    • name — Name of the file.
    • destination — Where to copy it to.
  • require-dir — Similar to require-file, but instead copies a whole directory. Attributes:
    • name — Name of the directory.
    • destination — Where to copy it to.
  • create-dir — Create a new directory.
    • name — Name of the new directory.
    • destination — Where to create it.
  • create-file — Create a blank file.
    • name — What to call the file.
    • destination — Where to create it.
  • move-dir — Move a directory from one place to another. Note: This is not for copying a directory from the package archive... Use require-dir for that!
    • name — Name of the directory.
    • destination — Where to move it to.
  • move-file — Move a file from one place to another. Note: This is not for copying a file from the package archive... Use require-file for that!
    • name — Name of the file.
    • destination — Where to move it to.
  • remove-dir — Delete a directory. This is usually used in uninstall sections, to clean up files from your mod.
    • name — Path of the directory.
  • remove-file — Delete a file.
    • name — Path of the file.

[edit] File name variables

In all of the file name attributes, special variables can be used. It is recommended to use these variables, as a user's file structure may be different:

  • $boarddir — The SMF directory.
  • $sourcedir — The Sources directory.
  • $themedir or $themesdir — The Themes/default directory.
  • $languagedir or $languagesdir — the Themes/default/languages directory.
  • $imagedir or $imagesdir — The Themes/default/images directory.
Retrieved from "http://www.smfmods.org/wiki/Package-info.xml"
Personal tools