Run Gaia Sky
************
This section contains information on how to run the software depending on
the install method.
Run regular installation
========================
If you installed the software using an installer or a package manager
system (``rpm``, ``deb``, `aur <https://aur.archlinux.org>`__), you just need to use the standard running
procedures of your Operating System to run the application.
Linux
-----
Just type :command:`gaiasky` in a terminal or use your favourite desktop
environment search engine to run the Gaia Sky launcher.
Windows
-------
In windows, this means clicking on ``Start`` and then browsing the start
menu folder ``Gaia Sky``. You can run the executable from there.
macOS
-----
Locate the launcher in your install directory (usually ``/Applications``) and double click on it.
**Code and pakcage**
However, if you are a maverick and do not like installers, you can also
run the Gaia Sky directly from the source code in ``GitHub`` or
using the ``tgz`` package.
Flatpak
=======
If you installed the flatpak from `flathub <https://flathub.org/apps/details/de.uni_heidelberg.zah.GaiaSky>`__, you can run it by using the application menu in your distro, or by firing up a terminal and writing:
.. code:: console
$ flatpak run de.uni_heidelberg.zah.GaiaSky
Appimage
========
In order to run the AppImage, just download the file, give it execute permissions, and run it.
TAR.GZ package
==============
You can also run the software using the ``tar.gz`` package without need for
an installation. To do so, extract the archive to your desired location and
run the :command:`gaiasky` script (Linux, macOS), or the :command:`gaiasky.cmd` batch file (Windows).
.. code:: console
$ tar -xzvf gaiasky-[version].tar.gz
$ cd gaiasky-[version]
$ gaiasky #Linux/macOS
$ .\gaiasky.cmd #Windows
.. _running-from-source:
Run from source
===============
Requirements
------------
If you want to compile the source code, you will need the following:
- Java Development Kit (``JDK``, version 17 or above should suffice, we recommend using the latest LTS available)
- ``git``
Please, be aware that only ``tags`` are guaranteed to work
(`here <https://codeberg.org/gaiasky/gaiasky/tags>`__). The ``master``
branch holds the development version and the configuration files are
possibly messed up and not ready to work out-of-the-box. So remember to
use a ``tag`` version if you want to run it right away from source.
First, clone the repository:
.. code:: console
$ git clone https://codeberg.org/gaiasky/gaiasky.git
Getting the catalog data
------------------------
.. hint:: As of version ``2.1.0``, Gaia Sky provides a self-contained download manager to get all the data packs available.
The `Base data pack` (key: ``default-data``) is necessary for Gaia Sky to run, and contains the Solar System, the Milky Way model, etc. Catalog files are optional but recommended if you want to see any stars at all. You can bring up the download manager at any time by clicking on the button :guilabel:``Dataset manager`` in the data tab of the preferences window. More information on the download manager can be found in :ref:`download-manager`.
You can also download the data packs manually `here <https://gaia.ari.uni-heidelberg.de/gaiasky/repository>`_.
Compiling and running
---------------------
To compile the code and run Gaia Sky run the following.
.. code:: console
$ gradlew core:run
If you want to pass CLI arguments via gradle, just use the gradle :samp:`--args` argument (:command:`gradlew core:run --args='-vr'`).
**Tip**: Gaia Sky checks that your Java version is compatible with it when you run the build. Skip this check by setting the ``GS_JAVA_VERSION_CHECK`` environment variable to `false` in the context of gradle:
.. code:: console
$ export GS_JAVA_VERSION_CHECK=false
In order to pull the latest changes from the remote git repository:
.. code:: console
$ git pull
On Windows, you need to open the Command Prompt (cmd, not PowerShell!) and run:
.. code:: console
.\gradlew.bat core:run
CLI arguments
=============
Gaia Sky offers a few command line arguments. Run :command:`gaiasky -h` for more information.
.. code:: console
$ gaiasky -h
Usage: gaiasky [options]
Options:
-h, --help
Show program options and usage information.
-v, --version
List Gaia Sky version and relevant information.
Default: false
-i, --asciiart
Add nice ascii art to --version information.
Default: false
-s, --skip-welcome
Skip the welcome screen if possible (base-data package must be present).
Default: false
-p, --properties
Specify the location of the properties file.
-a, --assets
Specify the location of the assets folder. If not present, the default
assets location (in the installation folder) is used.
-vr, --openvr
Launch in Virtual Reality mode. Gaia Sky will attempt to create a VR
context through OpenVR.
Default: false
-e, --externalview
Create a window with a view of the scene and no UI.
Default: false
-n, --noscript
Do not start the scripting server. Useful to run more than one Gaia Sky
instance at once in the same machine.
Default: false
-d, --debug
Launch in debug mode. Prints out debug information from Gaia Sky to the
logs.
Default: false
-g, --gpudebug
Activate OpenGL debug mode. Prints out debug information from OpenGL to
the standard output.
Default: false
-l, --headless
Use headless (windowless) mode, for servers.
Default: false
--safemode
Activate safe graphics mode. This forces the creation of an OpenGL 3.2
context, and disables float buffers and tessellation.
Default: false
--nosafemode
Force deactivation of safe graphics mode. Warning: this bypasses
internal checks and may break things! Useful to get rid of safe graphics
mode in the settings.
Default: false
--hdpimode
The HDPI mode to use. Defines how HiDPI monitors are handled. Operating
systems may have a per-monitor HiDPI scale setting. The operating system
may report window width/height and mouse coordinates in a logical
coordinate system at a lower resolution than the actual physical
resolution. This setting allows you to specify whether you want to work
in logical or raw pixel units.
Default: Pixels
Possible Values: [Logical, Pixels]
Packaging the software
======================
Gaia Sky can be exported to be run as a standalone app. Right now, doing so is only supported from Linux. You need the utility :command:`help2man` in your path to generate the man pages. Remember to restart the gradle daemon after installing it. Then run:
.. code:: console
$ gradlew core:dist
This creates a new directory ``releases/gaiasky-[version].[revison]`` with the exported application. Run scripts are provided with the name :command:`gaiasky` (Linux, macOS) and :command:`gaiasky.cmd` (Windows).
Also, to export Gaia Sky into a ``tar.gz`` archive file, run the following:
.. code:: console
$ gradlew core:createTar
In order to produce the desktop installers for the various systems you
need a licensed version of Install4j. Additionally, you need a certificate for signing the Windows packages in ``$GS/assets/cert/cert.pfx``. Then, just run:
.. code:: console
$ gradlew core:pack -PwinKeystorePassword=PASSWORD
Where ``PASSWORD`` is the password of the certificate. This command produces the different OS packages (``.exe``, ``.dmg``, ``.deb``, ``.rpm``, etc.) of Gaia Sky and stores them in the ``releases/packages-[version].[revision]`` directory.