File location change for version 0.9.x

From Stellarium Wiki
Revision as of 16:37, 22 May 2007 by Matthewg42 (Talk | contribs)
Jump to: navigation, search

Version 0.9.x will have a different layout for the data and texture files to previous versions. What follows is the proposal document which describes the intentions and rationale behind the change. After that there is a short status.

Stellarium file re-organisation proposal
----------------------------------------

Please view with fixed width font - ASCII art below!

The current situation with files separated into two main groups - data and
textures - is not ideal for easily distributing extensions to Stellarium
in a convenient manner.  For example, to install a new landscape, a user
must install textures in the textures/landscapes directory, and then
edit the data/landscapes.ini file, adding a new section to the file.
This is way too complicated for the average user, not to mention being
difficult to un-install, and not so simple to split file locations so that
users can install a landscape in their personal directories on machines
where the Stellarium installation directory is no writable by that user
(i.e. ~/.stellarium for Linux).

It would be better to be able to distribute extensions as single files
(e.g. zip files), and the user would simply need to unzip the file into
one location - no editing ini files and so on.

A further possibility is an in-program installer for downloaded extension
.zip files (performing the unzipping and placement of files within
Stellarium).  Implementation of this idea might be rejected because of
unwanted dependencies.

Another further possibility is to have Stellarium fetch extensions from
a specially formatted page on the Stellarium website which would list
known extensions and provide download links.  Again the implementation
of this idea might be rejected to avoid code bloat.


The extensions I have in mind are:

* Landscapes

* Scripts (The directory moves out of the data directory, although all scripts remain in a single directory to improve backward compatibility for Digitalis users).

* Sky Cultures (constellations, art and star names)

* Nebulae packages (sets of images of nebulae).


To facilitate easier extensions, I propose the following changes to the
way the files are laid out:

* For each type of extension, having a directory at the same level as
  the data & textures directories, named after the extension type,
  i.e. landscapes, scripts, nebulae

* Each extension would have a sub-directory in the extension type
  directory. Instead of adding a section to an existing .ini file,
  each extension would have it's own .ini file in it's own directory,
  as well as all other files (.PNGs etc.).  This makes un-installation
  trivial - just a matter of deleting the extension directory and all
  files inside it.


For example, the directory structure might look like this.  Thhis tree
would exist in the config directory, where the data and textures
sub-directories currently reside:

-+--data--...
 +--textures--...
 +--landscapes--+--guereins---+--landscape.ini
 |              |             +--guereinsb.png
 |              |             +--guereins1.png
 |              |             +--...
 |              |             +--guereins8.png
 |              |
 |              +--hurricane--...
 |              +--trees------...
 |              +--moon-------...
 |              +--ocean------...
 |
 +--scripts--+--startup.sts
 |           +--lunar_eclipse_total.sts
 |           +--lunar_eclipse_partial.sts
 |           +--solar_eclipse_total.sts
 |           +--info1.png
 |           +--info2.png
 |
 +--stars--+--default--+--stars0.cat
 |         |           +--stars1.cat
 |         |           +--stars2.cat
 |         |           +--stars3.cat
 |         |           +--stars_hip_sp.cat
 |         |           +--stars_hip_component_ids.cat
 |         |           +--name.fab
 |         |           +--double_txt.dat
 |         |
 |         +--mystars--+--stars0.cat
 |                     +--...
 |
 +--nebulae--+--default-------+--nebula_textures.fab
 |           |                +--m1.png
 |           |                +--m2.png
 |           |                +--...
 |           |
 |           +--jodrell_bank--+--nebula_textures.fab
 |                            +--irc10420.png
 |
 +--skycultures--+--western--+--info.ini
                 |           +--constellationship.fab
                 |           +--...
                 |
                 +--chinese------...
                 +--polynesian---...
                 +--usercult-----...
                 +--thirdparty---...


For each extension type, Stellarium would search for a sub-directory
which contains the necessary files for that extension, and load them
if they are found.  This mechanism would replace "global" .ini files
which list extensions, as is currently done with landscapes in the global
landscapes.ini file.  The existing sky cultures loading mechanism already
implements this sort of behaviour (svn r1728).

By loading extensions based on the existence of files we can avoid having
to edit .ini files to add extensions.  This is a major benefit for third
party extension makers.  It also makes removal of extensions a trivial
matter - simply to remove the directory in which they reside.

When Stellarium searches for the files for a given extension type, it
should look in both the global directory, and the user's private config
directory ($HOME/.stellarium on Linux etc).  This would enable users who
are not administrators to maintain their own extensions (personalised
landscapes and so on).

The old "data" and "textures" sub-directories of the config root area
would be preserved, but used only for those files which are not part of
extensions, e.g. the default_config.ini, ssystem.ini, the textures for
the toolbar buttons and splash screen etc...


Packaging of extensions
-----------------------

Extensions would be downloaded as single .zip files which would contain
the directory structure.  E.g. a landscape extension file might looks
like this:

filename: mylandscape.zip
contents:

 landscapes--mylandscape--+--landscape.ini
                          +--README
                          +--mylandscapeb.png
                          +--mylandscape1.png
                          +--mylandscape2.png
                          +--mylandscape3.png
                          +--mylandscape4.png
                          +--mylandscape5.png
                          +--mylandscape6.png
                          +--mylandscape7.png
                          +--mylandscape8.png

From the directory structure, it is easy to determine that this extension
contains a landscape called "mylandscape".  A user could install this
locally by just unzipping it in their ~/.stellarium directory.

ZIP files are a good packaging format because implementations of tools to
create and manipulate them are available on all platforms.  Other formats
might be considered, e.g. .tar.gz or .tar.bz2?  ZIP files have one major
drawback - two files with the same name - even in different directories
are not permitted in some popular ZIP implementations.  This could cause
a problem if two extensions were put in the single file (e.g. two sky
cultures would necessitate two landscape.ini files).


Benefits
--------

* Easier for third parties to produce and distribute landscapes, scripts, etc.

* We could make a set of extensions with larger data-sets for users who
  have a lot of bandwidth / space, but keep the default install nice
  and small.   We could probably do this already, but it wouldn't be
  nearly no neat.

* potential to separate out material under different licenses into
  free-standing extensions.  This would make it easier to manage
  donated nebula textures which have differing terms of use.

* It's pleasing to my mind


Drawbacks
---------

* Development time

* Increased implementation complexity (although we already do something
  like this with sky cultures).

* Increased startup time (searching for existence of files is probably
  taking a bit longer than having lots of settings in one file)

Contents

Status

2007-02-07

The landscapes change has been done, other files remain in their original locations.

2007-05-16

In the last week or so the following items have been completed:

  • nebulae
  • scripts
  • skycultures

Nebula notes: classes still need some extra features to make them work with more than one set of nebula images at once, and to unload groups of images etc.

Sky culture notes: constellation boundaries and scientific names are still hard-coded to turn off when culture != "western". It would be better to enable/disable these based on the existence of the relevant data file in a culture directory.

2007-05-22

It's all more or less done now. Scripts have been put in a single directory again. landscape.ini files now have a standard [landscape] section instead of a section named after the parent directory.

Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox