Help:Installation 1.6.0 - 1.6.2
This page describes how to install Semantic MediaWiki 1.6.0, 1.6.1 or 1.6.2 after having downloaded it (see the bottom of this page for other versions). Installation and upgrade notes change from version to version: the file INSTALL shipped with SMW contains instructions for the particular version you may have downloaded.
To upgrade a wiki running an older version of SMW, please make sure to have read the relevant section before starting the upgrade.
For installing SMW, please check the exact requirements and follow the instructions carefully. The installation does no irreversible changes to your MediaWiki database (it just adds some tables that can be deleted again). However, there is currently no automated process to remove annotations from articles texts in the case that Semantic MediaWiki is to be uninstalled again, but one could achieve this with some script that eliminates annotations on editing.
Disclaimer
Make sure you understand the legal disclaimer in the file COPYING.
Requirements
- MediaWiki 1.15.0 or greater (tested up to version 1.18alpha (r88635)).
- Validator extension version 0.4.7 or greater
- PHP 5.* or greater installed and working (except for version 5.3.1)
- MySQL >= 4.0.14 (version required by MediaWiki, except for versions 5.1.49 to 5.1.52)
- or PostgreSQL >= 8.3 (note that support for the latter is still preliminary and requires some extra steps, see PostgreSQL for details)
- Notes
- SMW uses the PHP mb_*() multibyte functions such as mb_strpos in the php_mbstring.dll extension. This is standard but not enabled by default on some distributions of PHP. See the PHP manual for details.
- For installation and upgrade, SMW needs the rights to create new tables (CREATE) and to alter tables (ALTER TABLE). Both can be removed again after SMW was set up. The script SMW_setup.php can use the DB credentials from AdminSettings.php for this purpose, avoiding the need of extra rights for the wiki DB user.
- When using SMWSQLStore2 (default data store for SMW), SMW creates and alters temporary tables for certain semantic queries. To do this, your wikidb user must have privileges for CREATE TEMPORARY TABLES. The according features can be disabled by adding the following to Localsettings.php:
$smwgQSubcategoryDepth= 0;
$smwgQPropertyDepth = 0;
$smwgQFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY;
$smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY &
~SMW_CONCEPT_QUERY;
- When using SMWSparqlStore (RDF store connector), SMW uses the CURL functions of PHP. These functions may have to be enabled/installed to be available.
- Running SMW on older versions of MediaWiki
In general, it is not recommended to run older versions of MediaWiki, since every new release brings also security fixes. If your site is still running on PHP4, SMW is not supported. It would hardly be possible to backport the code to the old PHP version. If you have PHP5 but an older MediaWiki version, additional patches/modifications might be needed. Download an older release of SMW and have a look at the included INSTALL instructions to find out whether other changes are recommended therein.
Installation
If you upgrade an existing installation of Semantic MediaWiki, also read the remarks in the section Upgrading existing installations below! Installing SMW basically requires three (or four) easy steps:
(1) Copy files. Extract the downloaded archives for Validator and Semantic MediaWiki, or check out the current files from SVN to obtain the directories "Validator" and "SemanticMediaWiki" that contain all relevant files. Copy these directories to "[wikipath]/extensions/" (or extract/download it to this place).
(2) [optional] Adjust namespaces. If you did not make any change the your wiki's namespaces, you can skip this step. If you have defined your own custom namespaces, you have to set the parameter $smwgNamespaceIndex before including SemanticMediaWiki.php. Semantic MediaWiki uses additional namespace indexes, in the range from 102 to 109. Note, 104 and 105 are only needed if $smwgHistoricTypeNamespace is set. 106 and 107 are reserved for the Semantic Forms extension and not used by SMW. See the documentation within SMW_Settings.php for details. If you add namespaces after installing SMW, then you have to assign them to higher numbers than those used by Semantic MediaWiki.
Note: Semantic MediaWiki only evaluates semantic annotations in some namespaces. For example, by default it ignores semantic annotations in talk pages. If you want to change the namespaces with annotations (likely if you have added your own custom namespaces), then you have to add the desired array for parameter $smwgNamespacesWithSemanticLinks in LocalSettings.php.
(3) Enable the extensions. Insert the following lines into the file "[wikipath]/LocalSettings.php":
require_once( "$IP/extensions/Validator/Validator.php" );
include_once( "$IP/extensions/SemanticMediaWiki/SemanticMediaWiki.php" );
enableSemantics('example.org');
where example.org should be replaced by your server's name (or IP address). This string is only used as a globally unique name for identifying the wiki's exported data on the Semantic Web, and a valid server name works very well for that purpose. There is no need to worry if a wiki has more than one server name – just pick one.
(4) Setup database. In your wiki, log in as a user with admin status and go to the page "Special:SMWAdmin" to do the final setup steps. Two steps are needed: at first, trigger the database setup ("Database installation and upgrade"). Afterwards, activate the automatic data update ("Data repair and upgrade"). Note that the first step requires permissions to alter/create database tables, as explained in the above note. The second step takes some time; go to Special:SMWAdmin to follow its progress. SMW can be used before this completes, but will not have access to all data yet (e.g. page categories).
File:Admin functions for Semantic MediaWiki.png Special:SMWAdmin |
File:Setting up Storage for Semantic MediaWiki.png Storage was successfully set up |
Testing your Installation
If you are uncertain that everything went well, you can do some testing steps to check if SMW is set up properly:
- Go to the Special:Version page. You should see Semantic MediaWiki (Version nn) listed in the top section "Semantic Extensions".
- Create a regular wiki page named "TestSMW", and in it enter the wiki text
Property test: [[testproperty::Dummypage]]
When previewing the page before saving, you should see a Factbox at the bottom of the article that shows your input. After saving the page, click on the link "Browse properties" in the page's toolbox. This view should show Testproperty with value Dummypage.
Upgrading existing installations
Note that SMW 1.6.0 has a new software dependency: the Validator extension that helps Semantic MediaWiki to validate user-provided parameters. It must be installed for SMW to work. Make sure that you include Validator prior to the inclusion of SMW in your LocalSettings.php. Do note that Validator comes bundled with SMW releases as of version 1.6.0. If you are obtaining the code via svn, you will need to get a checkout of Validator yourself.
Upgrading SMW 1.6.0
Installations of SMW 1.6.0 can be upgraded by just replacing the files, but it must be noted that not all SMW extensions may already be available in versions compatible to SMW 1.6.1.
Upgrading from SMW 1.5.0 to 1.5.6
Installations of SMW 1.5.* and can be upgraded by replacing the files, and by running the database update (Special:SMWAdmin or SMW_setup.php script) as usual. Moreover, it is strongly suggested to enable the refresh process to update all data on Special:SMWAdmin. Older versions of SMW can be upgraded in the same way, but there can be more feature changes that require changes of wiki pages. See the current documentation for details on using the current version.
Do not forget to also install the extension Validator first and include it in LocalSettings.php prior to SMW with the following line of code. After that you may proceed to upgrade SMW.
require_once( "$IP/extensions/Validator/Validator.php" );
Extensions for SMW versions up to 1.5.* should not be assumed to work with SMW 1.6.0 out of the box. All SMW extensions should be upgraded to versions that are compatible with SMW 1.6. Moreover, some functions changed and pages might need updates (see below). Additional remarks on upgrading older SMW versions are given below.
If not done already, it is suggested to change the inclusion of SMW in LocalSettings.php to the following as described in the installation instructions above:
include_once("$IP/extensions/SemanticMediaWiki/SemanticMediaWiki.php");
Including SMW_Settings.php as in earlier versions will continue to work, but may be disabled in some future version.
The main user-visible changes in SMW 1.6.0 concern the Type namespace, the use of custom units of measurement (with custom conversion factors), and the declaration of Type:Record properties. Moreover, the support for the RAP (RAP - RDF API) was replaced by general RDF store support. Please see the documentation for details on how to configure this.
Type namespace
SMW no longer uses namespaces "Type" and "Type talk." All types are now built-in and there is no good reason to keep a namespace just for documenting them. A new function of Special:Types allows viewing all properties of a type, like the Type pages did before.
If you still want to use Type (for example to access pages that existed there), you should set $smwgHistoricTypeNamespace = true; before including SMW in LocalSettings.php. This should only be used to move old content to a better place, e.g. to the Help namespace and to remove links still pointing to it. The old namespaces will not be kept indefinitely.
Custom units
The only use of Type pages was the declaration of custom types that would allow unit conversion. The declaration of properties with custom units of measurement has changed in two ways:
- The type of these properties is now "Quantity" (not a "custom" type page)
- The conversion factors that used to be on the Type page are now given on the property page. So one can simply move this text (Type must be activated for this as described above).
The internal data format of SMW has not changed for custom units, so stored data will be accessible immediately after the change.
Type:Record
The fields declaration of Record properties now refer to properties, not to types. If you have a property with
[[has type::Record]]
that uses a setting like
[[has fields::Page; Number; String]]
then you should now replace it with something like
[[has fields::my page; my number; my string]]
where "my page", "my number", and "my string" are properties in your wiki that have the right types. The use of properties instead of types is better since it allows custom settings beyond the datatype of a field (e.g. conversion factors).
The new method also involves internal changes in the data format, and it is not possible to make the update without temporarily loosing access to the stored data for Type:Record properties (until SMW's self repair has fixed all data entries).
Upgrading SMW 1.4.3 or lower
Users who update from SMW 1.4.0 or earlier should note that "n-ary" properties now are declared by properties of Type:Record as explained below, and that support for geographic coordinates has moved to the Semantic Maps extension. For upgrading earlier SMW versions, users should have a look at upgrade instructions released with SMW 1.5.x.
Changed configuration options
Some configuration options (used in LocalSettings.php) have changed since SMW 1.0. All settings are documented in detail in the file SMW_Settings.php. The following list gives the version in which a setting was first introduced, so it can be ignored if you already run this version or a more recent one.
- [1.4] Up to version 1.4, the default for value for the setting $smwgQComparators was '<|>|!'. It now has changed to '<|>|!|~' so the "like" comparator ~ is enabled by default.
- [1.4] Version 1.4 still supported a setting $smwgSMWBetaCompatible to enable the old <ask> query syntax and the Relation namespace. This backwards compatibility has now been dropped and the setting is no longer used. Please update your wiki to not use the outdated (and now undocumented) features.
- [1.3] Since SMW 1.3, the Factbox is hidden by default and will only appear in page previews. As a compensation, the toolbox (usually on the left below the search field) shows a link to Special:Browse. To use the display behaviour of the Factbox as it was before SMW 1.3, set $smwgShowFactbox = SMW_FACTBOX_NONEMPTY; The new link and the Factbox during editing can also be configured; see SMW_Settings.php for details.
- [1.2.1] SMW will no longer support nested link syntax in property values by default, since this was known to cause problems. To re-enable this, set $smwgLinksInValues = true;
- [1.2] If your wiki uses <ask> syntax or the Relation: namespace, you may want to set $smwgSMWBetaCompatible = true; before the line including SemanticMediaWiki.php (formerly SMW_Settings.php) in LocalSettings.php. Consider changing <ask> to #ask to be able to drop SMW beta compatibility.
- [1.2] If you had a setting $smwgQDisjunctionSupport = false; then you now need the following settings in your LocalSettings.php:
$smwgQFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY;
$smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY;
- [1.0] $smwgQEqualitySupport is one of SMW_EQ_NONE, SMW_EQ_SOME, SMW_EQ_FULL (it was true or false until SMW 1.0 RC1-3).
- [1.0] $smwgQDefaultNamespaces is now NULL by default, so that all namespaces are queried. The default in SMW RC 1-3 was 'array(NS_MAIN, NS_IMAGE)'.
- [1.0] $smwgQDefaultLinking now defaults to 'all' such that all query results are linked. This is not a performance issue any more. The default until SMW RC 1-3 was 'subject'.
If you currently set any of these parameters in your LocalSettings.php, you need to update this file. Please see SMW_Settings.php for more documentation on the available parameters.
Property "Namespace" has a restricted application area and cannot be used as annotation property by a user.Property "Docinfo editor" (as page type) with input value "User:>Kghbln" contains invalid characters or is incomplete and therefore can cause unexpected results during a query or annotation process.
