Changes: Creating freeciv-modpack content

Revision as of 12:30, 16 February 2020

Since version 2.3 freeciv contains a modpack installer (freeciv-modpack or freeciv-mp-*) for downloading and installing custom content. Users only need to enter a modpack URL, and it will be automatically correctly installed. Users are no more forced to download and copy each file to the correct directory manually, where correct was something that nobody seemed to know what it is for some operating systems.

As of 2.6.x, how to use the tool, and how you as custom modpack author can publish your content are documented in doc/README.modpack_installer in the source distribution. This page mainly has notes on the history.

If you really need to publish a modpack for a pre-2.6 version of Freeciv, you're probably best starting at 2.6 docs and working backward, using files on modpack.freeciv.org as a reference; or you can look at old versions of this page for some more detail.

Version	Flavours	List capability	Modpack capability	Full docs	Notes
2.3	Gtk2	`+Freeciv-2.3-modlist`	`+modpack-090810-2`	-	List URL was hardcoded to server that no longer exists. (Copy preserved on files.freeciv.org.)
2.4	Gtk2	`+modlist-011111`	`+modpack-150611`	-	Added scenario/soundset types. List URL and installation prefix changeable at runtime. Replaced homegrown network access with more reliable Curl library.
2.5	Gtk2/3, Qt, cli	`+Freeciv-2.5-modlist`	`+Freeciv-2.5-modpack`	-	Added descriptions and subtype. Installer started recording history of installed modpacks.
2.6	Gtk2/3, Qt, cli	See docs		git	Added dependencies, relative URLs. Added "Musicset" type.
3.0 (TBC)	Gtk2/3/4, Qt, cli	See docs		git	TBC

Stable versions default to getting modpacks from modpack.freeciv.org, curated by the Freeciv team.

Early development code currently defaults to an experimental area on files.freeciv.org instead. These are maintained by developers as needed for testing, and aren't guaranteed to exist / work at any given time. The "dev" subdirectory is used for the master branch; the "test" directory is used by a stabilising branched version up until data format freeze (see Release Cycle), at which point modpacks move to modpack.freeciv.org.

@@ Line 1: / Line 1: @@
+[[File:Freeciv-modpack.png|thumb|Modpack UI icon]] <!-- this should float to the left of the next section -->
-{| style="float:left; margin-right:1em"
+Since version 2.3 freeciv contains a ''modpack installer'' (freeciv-modpack or freeciv-mp-*) for downloading and installing custom content. Users only need to enter a modpack URL, and it will be automatically correctly installed. Users are no more forced to download and copy each file to the correct directory manually, where ''correct'' was something that nobody seemed to know what it is for some operating systems.
-|__TOC__
-|}
+As of 2.6.x, how to use the tool, and how you as custom modpack author can publish your content are documented in <tt>doc/README.modpack_installer</tt> in the source distribution. This page mainly has notes on the history.
-Since version 2.3 freeciv contains a ''modpack installer'' (freeciv-modpack) for downloading and installing custom content. Users only need to enter a modpack URL, and it will be automatically correctly installed. Users are not more forced to download and copy each file to the correct directory manually, where ''correct'' was something that nobody seemed to know what it is for some operating systems. This document describes how you as custom modpack author can make your content available for an installation with freeciv-modpack.
+If you really need to publish a modpack for a pre-2.6 version of Freeciv, you're probably best starting at 2.6 docs and working backward, using files on [http://modpack.freeciv.org modpack.freeciv.org] as a reference; or you can look at old versions of this page for some more detail.
-==Hosting place==
+{| border=1
-First of all you need some place in the Internet to store your modpack where freeciv-modpack can fetch it from. Current versions of freeciv-modpack support downloading only by http, so you need content on a web-server, e.g., your homepage, but not an ftp-server. Currently freeciv-modpack has no way to unpack any archives, and each file of your modpack must be separately downloadable. Individual sceanarios can be of course compressed (gzip or xz, ''bzip2 will be removed''.)
+! Version
+! Flavours
-==.modpack-file==
+! List capability
+! Modpack capability
-In addition to all the normal contents of your modpack you have to create one file that instructs freeciv-modpack in the download process. This file must have a .modpack-suffix and it determines the modpack URL specified by the user in freeciv-modpack. It is a text file similar to other data file formats freeciv uses, so you as modpack author are already quite familiar with the INI-like syntax of this format.
+! Full docs
+! Notes
-  [info]
+|-
-  options = "+modpack-090810-2"
+| 2.3
-  baseURL = "<span class="plainlinks">http://www.cazfi.net/freeciv/modinst/2.3/ancients</span>"
+| Gtk2
-  name = "Example"  '''Since 2.4'''
+| <tt>+Freeciv-2.3-modlist</tt>
-  type = "Ruleset"  '''Since 2.4'''
+| <tt>+modpack-090810-2</tt>
-  version = "1.0-beta2" '''Since 2.4'''
+| -
+| List URL was hardcoded to server that no longer exists.<br>(Copy preserved [http://modpack.freeciv.org/2.3/modpack.list on files.freeciv.org].)
-  [files]
+|-
-  list =
+| 2.4
-  {
+| Gtk2
-    "src", "dest"
+| <tt>+modlist-011111</tt>
-    "ancients.serv"
+| <tt>+modpack-150611</tt>
-    "ancients.tilespec"
+| -
-    "ancients/nation/german.ruleset"
+| Added scenario/soundset types.<br>List URL and installation prefix changeable at runtime.<br>Replaced homegrown network access with more reliable Curl library.
-    ...
+|-
-    "ancients/README"
+| 2.5
-  }
+| Gtk2/3, Qt, cli
+| <tt>+Freeciv-2.5-modlist</tt>
-''info.options'' gives a capability string of this modpack-file. For content to be downloaded with the freeciv 2.3 freeciv-modpack this must be "+modpack-090810-2", and for 2.4 it must be "+modpack-150611".
+| <tt>+Freeciv-2.5-modpack</tt>
+| -
-''info.baseURL'' gives a common beginning of the URLs files can be downloaded from, so you don't need to give full URL for every file in your modpack. In the above example all the files of the ancients.modpack are placed under the directory http://www.cazfi.net/freeciv/modinst/2.3/ancients.
+| Added descriptions and subtype.<br>Installer started recording history of installed modpacks.
+|-
-''info.name'' is the name of the modpack.
+| 2.6
+| Gtk2/3, Qt, cli
-''info.type'' is the type of this custom content package; one of "Ruleset", "Tileset", "Modpack", or "Scenario". This affects where content gets installed. Scenarios (consisting only of one optionally compressed .sav faile) are freeciv version independent and stored in a location shared by all freeciv versions, typically <code>~/.freeciv/scenarios</code>. All other types belong to a specific freeciv version (a "branch" in SVN terminology, e.g., 2.5), and are installed under a version specific directory, e.g., <code>~/.freeciv/2.5/name</code>.
+| colspan=2 | See docs
+| {{CodeSourceRaw|branch=S2_6|doc/README.modpack_installer|git}}
-''info.version'' is a version string for your modpack.
+| Added dependencies, relative URLs.<br>Added "Musicset" type.
+|-
-''files.list'' is the list of files to download. For each file at least '''src''' must be given. It is the end of the URL for this particular file. The first file to download in the example above is http://www.cazfi.net/freeciv/modinst/2.3/ancients/ancients.serv. '''dest''' is what the file should be called when installed, relative to the main installation directory. If '''dest''' is omitted, '''src''' is used for this too.
+| 3.0 (TBC)
+| Gtk2/3/4, Qt, cli
-==Background==
+| colspan=2 | See docs
-[[File:Freeciv-modpack.png|thumb|Modpack UI icon]]
+| {{CodeSourceRaw|branch=S3_0|doc/README.modpack_installer|git}}
-:''Not really relevant for '''modpack''' authors, just for the records.''
+| TBC
+|}
-===modpack.list===
-:''Modpack installation procedures used for 2.3 and partially 2.4:''
-The <code>modpack.list</code> is a list maintained by the freeciv team about high profile .modpack files. The URL for that list is hardcoded to freeciv-modpack, and for freeciv 2.3 it was <span class="plainlinks">[http://download.gna.org/freeciv/modinst/2.3/modpack.list http://download.gna.org/freeciv/modinst/2.3/modpack.list]</span>. To install a modpack from that list users do not need to know any URLs at all. Since 2.4 it is possible to override the URL with a commandline parameter "-L <URL>". This is mainly meant for testing freeciv-modpack during development.
-  [info]
-  options = "+Freeciv-2.3-modlist"
-  message = "Freeciv 2.3 is expected to be released quite soon now."
-  [modpacks]
-  list =
-  {
-    "name", "version", "type", "license", "URL"
-    "Amplio", "S2_3", "Tileset", "GLP2+", "<span class="plainlinks">http://www.cazfi.net/freeciv/modinst/2.3/amplio.modpack</span>"
-    "Ancients", "2.3-0", "Ruleset", "GPL2+", "<span class="plainlinks">http://www.cazfi.net/freeciv/modinst/2.3/ancients.modpack</span>"
-  }
-''info.options'' is the capability string of this modpack.list file. For a list compatible with freeciv 2.3 freeciv-modpack it must be "+Freeciv-2.3-modlist", and for freeciv 2.4 it must be "+modlist-011111".
-''info.message'' is an optional message to be shown over a freeciv-modpack connection.
-''modpacks.list'' is a list of .modpack-files. The ''name'' and ''version'' are currently just texts to be shown to the user. The ''type'' is one of ''Ruleset'', ''Tileset'', ''Modpack'', or, starting from 2.4, ''Scenario''. The ''license'' is a new field in 2.4 containing the name of the modpack's license. ''URL'' is where the .modpack file can be downloaded.
-=== modpack.db ===
-:''Modpack installation procedures used for 2.5 and partially 2.4:''
-As of version 2.5 the modpack installer saves information about locally installed modpacks to a <code>modpack.db</code> file. The <code>.db</code> file extension is arguably a bad idea for Windows, maybe 2.6 or later pick something less ambiguous, e.g., <code>~/.freeciv/3.0/.control/modpack.spec</code> could be good enough ({{Gna|24673}}).
+Stable versions default to getting modpacks from [http://modpack.freeciv.org/ modpack.freeciv.org], curated by the Freeciv team.
-The <code>~/.freeciv/2.5/.control/modpack.db</code> is created by the relevant ''modpack installer'' based on what you have installed from [http://modpack.freeciv.org/2.5/ modpack.freeciv.org/2.5] (default) or similar servers. Based on <code>modpack.list</code> files on the default server for [http://modpack.freeciv.org/2.4/modpack.list 2.4], [http://modpack.freeciv.org/2.5/modpack.list 2.5], [http://modpack.freeciv.org/2.6/modpack.list 2.6], and later the ''modpack installer'' can also determine which modpacks are not yet installed or not the latest version.
+Early development code currently defaults to [http://files.freeciv.org/modinst/ an experimental area on files.freeciv.org] instead. These are maintained by developers as needed for testing, and aren't guaranteed to exist / work at any given time. The "dev" subdirectory is used for the master branch; the "test" directory is used by a stabilising branched version up until data format freeze (see [[Release Cycle]]), at which point modpacks move to modpack.freeciv.org.
-=== UIs ===
+[[Category:Game mods]]
-For Freeciv 2.5 the former <code>freeciv-modpack.exe</code> (on Windows) was renamed to <code>freeciv-mp-UI.exe</code> for UI gtk2, gtk3, sdl, qt, and more. For Freeciv 2.6 and later there will be also a command line modpack installer. ''TBD: It's not obvious what "Portable APPs" (PAF) distributions will use as'' <code>~/.freeciv</code> ''home directory; please add some details here or link to a new PAF page on this wiki with more "Portable APPs" observations.''