{{{
#!comment
<LEFT-MENU>
}}}
{{{
#!div style="width:15%; float:left; clear:none; margin-right:1em; background:#ffb; border:1px solid #b00; padding-left:1em; padding-right:1em"
[wiki:WikiStart Home] [[BR]] [[BR]]
'''TOL''' [[BR]] [wiki:Software Software] [[BR]] [wiki:Download Download] [[BR]] [wiki:Installation Installation] [[BR]] [wiki:Packages Packages] [[BR]] [wiki:OTAN OTAN] [[BR]] [[BR]]
'''TOL Project''' [[BR]] [wiki:About About TOL] [[BR]] [wiki:Manuals Manuals] [[BR]] [wiki:Development Development] [[BR]] [wiki:Rprojects R-Projects] [[BR]] [[BR]]
'''Other Links''' [[BR]] [wiki:TracGuide Trac Guide] [[BR]] [wiki:WikiTree Wiki Tree] [[BR]] [https://mms.tol-project.org MMS]  
}}}
{{{
#!div style="margin-left:20%; margin-right:20%; padding-left:2em; padding-right:2em"
{{{
#!comment
</LEFT-MENU>
}}}

= TolPackage =

!TolPackage is a TOL '''module''' (part of TolCore) for the TOL-packages management: installation, updating and upgrading, loading, creation, etc.

== Functionalities ==

!TolPackage has different versions linked to the package design evolution and requirements (see [wiki:TolPackage#History History]).

The main functionalities described below are available from !TolPackage version 2 onwards.

=== Package installation ===

A package is automatically installed the first time it is required ({{{#Require}}}). 

{{{
#!cpp
#Require <package>;
}}}

However, an installation can be carried out manually via the {{{InstallPackage}}} function, indicating the
identifier (name and version) of the package desired for installation:

{{{
#!cpp
Real TolPackage:InstallPackage(<packageIdentifier>);
}}}

If you don't know the most recent version we can use the {{{InstallLastCompatible}}} function
and simply indicate the package name:

{{{
#!cpp
Real TolPackage:InstallLastCompatible(<packageName>);
}}}

=== Update and upgrade ===

Periodically, new versions of a package are created. So, you need update and upgrade your packages to stay up to date.

!TolPackage identifies two replacement mechanisms:

 * A package update, consisting of the substitution of the package for another more recent one, which has the same version numbers.

 * A package upgrade, consisting of the installation of a new version of the package. 
   Note that the previous version is not uninstalled.

A package update usually includes important corrections, since the reconstruction of a
package with the same version discards the previous one.

To update a package we can use the {{{Update}}} function, indicating the package name:
{{{
#!cpp
Real TolPackage::Update(<packageName>);
}}}

We can also update all the packages we have installed using the {{{UpdateAll}}} function:
{{{
#!cpp
Real TolPackage::UpdateAll(?);
}}}

A package upgrade is equally recommendable, as in many cases they include important advances
in the implemented procedures and algorithms.

To improve a unique package we can use the Upgrade function:
{{{
#!cpp
Real TolPackage::Upgrade(<packageName>);
}}}

And in a similar way, the {{{UpgradeAll}}} function, to improve all of the installed packages:
{{{
#!cpp
Real TolPackage::UpgradeAll(?);
}}}

=== Low version upgrade ===

In case of you wish to upgrade the low-version (second version number) of a package maintaining the high-version as it is, you have {{{the LowUpgrade}}} function. It is called using the package name and the first version number (high-version number):
{{{
#!cpp
Real TolPackage::LowUpgrade(<packageName.highVersion>);
}}}

Bear in mind that if you do not indicate a high-version when use {{{LowUpgrade}}}, an attempt would be made to upgrade
the low-version of all of the installed high-versions.

If you wish to obtain all of the upgrades for a package, you have the function {{{FullUpgrade}}} which joins calls to {{{Upgrade}}} and {{{LowUpgrade}}}:
{{{
#!cpp
Real TolPackage::FullUpgrade(<packageName>);
}}}

You also have functions for low- or full-upgrade all installed packages: {{{LowUpgradeAll}}} and {{{FullUpgradeAll}}}.

== History ==

The !TolPackage module evolves with the TOL-package design and enhacements, causing different versions with their own mechanisms and functionalities.

These versions are briefly described below.

=== Version 1 ===

!TolPackage first version has been distributed from TOL version {{{2.0.1}}} (see [2224]) to TOL versión {{{3.1 p009}}} (see [4535]).

This was the development version and it shows different enhancements in its two different subversions: {{{1.0}}} and {{{1.1}}}.

=== Version 2 ===

From TOL version {{{3.1 p010}}} (see [4622]) a new version of !TolPackage: {{{2}}} is available. This version was created to solve some difficulties with previous version.

=== Version 3 ===

To solve an OIS incompatibility in early patchs of TOL version {{{3.2}}} a new version of !TolPackage: {{{3}}} was created. This third version was used simultaneously with version {{{2}}}.

See tickets: #1541, #1533.

The mentioned incompatibility was solved in [5428] and since then the !TolPackage duality (versions {{{2}}} and {{{3}}} simultaneity) is no longer necessary.

=== Version 4 ===

New TOL versions for Windows (MinGW compiled) incorporate an incompatibility with TOL packages including binary libraries (.dll files). 

This difficulty causes the development of a new version: {{{4}}}. See ticket: #1821. 

!TolPackage.4 provides the possibility of managing different TOL-package variants (compatible with different TOL platforms) for the same TOL-package version.