File and Directory Structure - Revision history

Fabien: Moved to developer's doc.

2008-12-03T16:15:04Z

Moved to developer's doc.

Matthewg42 at 13:56, 2 December 2008

2008-12-02T13:56:17Z

Matthewg42: /* Finding files with the StelFilMgr class */

2008-11-23T16:42:29Z

Finding files with the StelFilMgr class

Matthewg42 at 16:39, 23 November 2008

2008-11-23T16:39:53Z

Matthewg42 at 16:37, 23 November 2008

2008-11-23T16:37:26Z

Matthewg42: New page: This article explains the directory and file layout which Stellarium uses from a programmers perspective, layout out the rationale behind it, and uses examples to illustrate the way things...

2008-11-23T16:23:27Z

New page: This article explains the directory and file layout which Stellarium uses from a programmers perspective, layout out the rationale behind it, and uses examples to illustrate the way things...

New page

This article explains the directory and file layout which Stellarium uses from a programmers perspective, layout out the rationale behind it, and uses examples to illustrate the way things work.

===Directory Structure===
Files are broadly separated by the type of data. For ''StelModules'' which need many data files, there is one directory. e.g. ''StarMgr'' files are stored in the ''stars'' directory, ''LandscapeMgr'' files may be found in the ''landscapes'' directory.

There are also directories which are shared among modules and other parts of the program, for example the ''textures'' directory.

===User and Installation directory separation===
When Stellarium searches for data, texture and other files it looks in two separate locations:
#The [[User Data Directory]], which stores per-user copies of any customised data files
#The [[Installation Directory]], which is where the program executable, libraries and all data files which are distributed with the program are installed.

If a file exists in the User Data Directory, it will be used in preference to a file with the same name existing in the Installation Directory. This allows users to customise data files, textures and so on without modifying the originally installed files.

There are several reasons for doing this:
#On machines which multiple user accounts, the Installation Directory will likely not be writable by all users. Without allowing the User Data Directory files to over-ride Installation Directory files such users could not customise the program without doing an entirely separate installation.
#On multi-user systems, different users can customise Stellarium without affecting other users of the program.
#Users who modify files in the Installation Directory will likely have their work deleted or overwritten when they upgrade Stellarium. By keeping user-customised files separate from the installation, the upgrade procedure is easier to manage, and users have better security for their work.
#Users who mess up a customisation attempt need only remove the User Data Directory copy of a file to return to the original (working) copy.

===Finding files with the StelFilMgr class===
Whenever a file is needed in Stellarium, it should be located using the ''StelFileMgr'' class. This class will find the file in the first location in the search path. An instance of this class is maintained by the ''StelApp'' singleton.

''StelFileMgr'' will throw exceptions when a problem is encountered, so it is important to always use "try ... catch ..." exception handling when using it.

For example. You are writing a class called ''Comet'', and wish to search for a data file called "comets.dat" located in the ''data'' directory, you would go about it like this:

QString path;
try
{
path = StelApp::getInstance().getFileMgr().findFile("data/comets.dat");
}
catch(std::exception& e)
{
qWarning() << "Could not locate file: data/comets.dat : " << e.what();
}

...

As you can see, the file is specified only by the partial path. This partial path is appended first to the User Data Directory. If, and only if the file is not found there, it is searched for in the installation directory. Thus if the user has a customised copy at: ''<User Data Directory>/data/comets.dat'' it will be used, else the version in the installation directory will be used.

===Example: Star Catalogue Download Tool===

@@ Line 1: / Line 1: @@
-This article explains the directory and file layout which Stellarium uses from a programmer's perspective, lays out the rationale behind it, and uses examples to illustrate the way things work.
+See http://www.stellarium.org/doc/head/fileStructure.html
-−
-===Directory Structure===
-Files are broadly separated by the type of data.  For ''StelModules'' which need many data files, there is one directory.  e.g. ''StarMgr'' files are stored in the ''stars'' directory, ''LandscapeMgr'' files may be found in the ''landscapes'' directory.
-−
-There are also directories which are shared among modules and other parts of the program, for example the ''textures'' directory.
-−
-===User and Installation directory separation===
-When Stellarium searches for data, texture and other files it looks in two separate locations:
-#The [[User Data Directory]], which stores per-user copies of any customised data files
-#The [[Installation Data Directory]], which is where the program executable, libraries and all data files which are distributed with the program are installed.
-−
-If a file exists in the User Data Directory, it will be used in preference to a file with the same name existing in the Installation Data Directory.  This allows users to customise data files, textures and so on without modifying the originally installed files.
-−
-There are several reasons for doing this:
-#On machines which multiple user accounts, the Installation Data Directory will likely not be writable by all users.  Without allowing the User Data Directory files to over-ride Installation Data Directory files such users could not customise the program without doing an entirely separate installation.
-#On multi-user systems, different users can customise Stellarium without affecting other users of the program.
-#Users who modify files in the Installation Data Directory will likely have their work deleted or overwritten when they upgrade Stellarium.  By keeping user-customised files separate from the installation, the upgrade procedure is easier to manage, and users have better security for their work.
-#Users who mess up a customisation attempt need only remove the User Data Directory copy of a file to return to the original (working) copy.
-−
-===Finding files with the StelFilMgr class===
-Whenever a file is needed in Stellarium, it should be located using the ''StelFileMgr'' class.  This class will find the file in the first location in the search path.  An instance of this class is maintained by the ''StelApp'' singleton.
-−
-''StelFileMgr'' will throw exceptions when a problem is encountered, so it is important to always use "try ... catch ..." exception handling when using it.
-−
-For example.  You are writing a class called ''Comet'', and wish to search for a data file called "comets.dat" located in the ''data'' directory, you would go about it like this:
-−
- QString path;
- try
-−
-         path = StelApp::getInstance().getFileMgr().findFile("data/comets.dat");
-−
- catch(std::runtime_error& e)
-−
-         qWarning() << "Could not locate file: data/comets.dat : " << e.what();
-−
-−
- ...
-−
-As you can see, the file is specified only by the partial path.  This partial path is appended first to the User Data Directory.  If, and only if the file is not found there, it is searched for in the Installation Data Directory.  Thus if the user has a customised copy at: ''<User Data Directory>/data/comets.dat'' it will be used, else the version in the Installation Data Directory will be used.
-−
-===Example: Star Catalogue Download Tool===
-Stellarium ships with the first four star catalogue files of nine files.  The implementation of a catalogue downloading tool helps ease the task for users wanting the extra catalogues by automating the download and installation procedure.
-−
-The files which come with Stellarium are found by the partial paths:
- stars/default/stars_0_0v0_1.cat
- stars/default/stars_1_0v0_1.cat
- stars/default/stars_2_0v0_1.cat
- stars/default/stars_3_1v0_1.cat
-−
-Naturally, these files are to be located in the Installation Data Directory (because they ship with the installer).
-−
-The catalogue downloader tool runs within Stellarium.  When it downloads extra star catalogue files, it should place them in the User Data Directory.  After downloading all the catalogues, the paths to the various files should look like this:
- <Installation Data Directory>/stars/default/stars_0_0v0_1.cat
- <Installation Data Directory>/stars/default/stars_1_0v0_1.cat
- <Installation Data Directory>/stars/default/stars_2_0v0_1.cat
- <Installation Data Directory>/stars/default/stars_3_1v0_1.cat
- <User Data Directory>/stars/default/stars_4_1v0_0.cat
- <User Data Directory>/stars/default/stars_5_2v0_0.cat
- <User Data Directory>/stars/default/stars_6_2v0_0.cat
- <User Data Directory>/stars/default/stars_7_2v0_0.cat
- <User Data Directory>/stars/default/stars_8_2v0_0.cat
-−
-−
-It might be that someone makes a customised installer of Stellarium which includes all the star catalogues with the main installation - perhaps on a special edition DVD.  In this case, all the files would be in the ''<Installation Data Directory>/stars/default'' directory.  The downloader tool should be able to cope with this, not re-downloading files into the User Data Directory which already reside in the Installation Data Directory.
 [[Category:Development]]

← Older revision		Revision as of 13:56, 2 December 2008
Line 64:		Line 64:

	It might be that someone makes a customised installer of Stellarium which includes all the star catalogues with the main installation - perhaps on a special edition DVD. In this case, all the files would be in the ''<Installation Data Directory>/stars/default'' directory. The downloader tool should be able to cope with this, not re-downloading files into the User Data Directory which already reside in the Installation Data Directory.		It might be that someone makes a customised installer of Stellarium which includes all the star catalogues with the main installation - perhaps on a special edition DVD. In this case, all the files would be in the ''<Installation Data Directory>/stars/default'' directory. The downloader tool should be able to cope with this, not re-downloading files into the User Data Directory which already reside in the Installation Data Directory.
		+
		+	[[Category:Development]]

← Older revision		Revision as of 16:39, 23 November 2008
Line 1:		Line 1:
−	This article explains the directory and file layout which Stellarium uses from a ~~programmers~~ perspective, ~~layout~~ out the rationale behind it, and uses examples to illustrate the way things work.	+	This article explains the directory and file layout which Stellarium uses from a programmer's perspective, lays out the rationale behind it, and uses examples to illustrate the way things work.

	===Directory Structure===		===Directory Structure===