..  vim: set expandtab shiftwidth=4 softtabstop=4:

================
ChimeraX Startup
================

The ChimeraX application runs on Microsoft Windows, macOS,
and Linux.

By default, ChimeraX does an asynchronous network query
of the ChimeraX Toolshed for available bundles at startup once a week.
The interval can be changed in the Toolshed settings.
The Toolshed query is implicitly turned off when certain command line arguments are given
as noted below.

Command Line Arguments
======================

When running ChimeraX from a terminal (*a.k.a.* a shell) it can be given
various options followed by data files.
The data files are specified with same syntax as the filename argument
of Models' :py:func:`~chimerax.core.models.Models.open`.

Command line options can start with either a single dash or a double dash
and may not be mixed.

Single Dash Commmand Line Options
---------------------------------

All of the Python single dash command line options are recognized.
The presence of any single dash argument turns off querying the Toolshed at startup.
Most are ignored except for the following:

``-c command``
    Only recognized if it is the first argument.
    Act like the Python interpreter and run the Python command
    with the rest of the arguments in :py:obj:`sys.argv`.
    Implies ``--nogui`` and ``--silent``.
    This is done after ChimeraX has started up, so a ChimeraX session
    is available in the global variable ``session``.

``-d``
    Turn on debugging.

``-h``
    Show command line help.

``-m module``
    Only recognized if it is the first argument.
    Act like the Python interpreter and run the module as the main module
    and the rest of the arguments are in :py:obj:`sys.argv`.
    Implies ``--nogui`` and ``--silent``.
    This is done after ChimeraX has started up, so a ChimeraX session
    is available in the global variable ``session``.
    The module name is ``__main__`` instead of a sandbox name that
    is used for normal :py:mod:`~chimerax.core.scripting`.

``-u``
    Force the stdout and stderr streams to be unbuffered.

``-V``
    Prints the internal Python version and exits.


Double Dash Command Line Options
--------------------------------

The follow command line arguments are recognized:

``--cmd command``

    Run the ChimeraX command at startup after starting tools.
    Turns off querying the Toolshed at startup.

``--color``
    Turn on colored text in nogui mode (default).

``--nocolor``
    Turn off colored text in nogui mode.

``--debug``
    Turn on debugging code.  Accessing within ChimeraX with ``session.debug``.

``--devel``
    Turn on development mode.  Currently, just enables Python deprecation warnings.

``--exit``
    Exit immediately after processing command line arguments.
    Turns off querying the Toolshed at startup.

``--noexit``
    Do not exit after processing command line arguments (default).
    Turns off querying the Toolshed at startup (not default).

``--lineprofile``
    Turn on line profiling.  See :ref:`line-profiling` for details.
    Turns off querying the Toolshed at startup.

``--listioformats``
    Show all recognized file suffixes and if they can be opened or saved.
    Turns off querying the Toolshed at startup.
    
``--nogui``
    Turn off the gui.  Access with ChimeraX with ``session.ui.is_gui``.

``--nostatus``
    Don't output to status line.

``--notools``
    Do not autostart any tools at startup.

``--offscreen``
    Run without a gui but allow rendering images that can be saved to files,
    *i.e.*, implies ``--nogui``.
    This uses OSMesa for rendering which will not make use of
    a GPU, so rendering can be slow.
    But it can run on a server without a display.

``--safemode``
    Don't run bundle custom initialization code nor load any tools.

``--script python-script``
    Run Python script at startup.
    If they Python script has any specific arguments,
    they should be quoted along with the script name.
    Turns off querying the Toolshed at startup.
    
``--silent``
    Don't output startup splash text and otherwise refrain from being
    verbose.

``--start_tool tool_name``

    Start the named tool during ChimeraX startup after the autostart tools.

``--tools``
    Run ChimeraX tools at startup (default).

``--notools``
    Don't run ChimeraX tools at startup.

``--toolshed URL``
    Set the URL to use for the toolshed.
    The special name **preview** is recognized for using a preview of
    the next revision of the toolshed (currently only available internally).

``--uninstall``
    If needed, deregister any icons or mime types,
    then remove as much of the installation directory as possible.
    Intended for use by system App Store or package manager.

``--usedefaults``
    Ignore user settings and use default settings.
    Not implemented yet.

``--version``
    Print out current version.
    If given two times,
    then all of installed ChimeraX tools verions are listed.
    If given three times,
    then all of installed Python package versions are listed.

Run Custom Python Code at Start Up
==================================

To have ChimeraX run custom Python code each time you start it you can put Python files
in directory

	~/chimerax_start

Each Python file will be executed with the variable "session" added to the global namespace.
For example, the following line put in ~/chimerax_start/starttools.py automatically starts
the File History panel and Density Map toolbar.

        session.tools.start_tools(('File History', 'Density Map Toolbar'))

Python code can be used to register new commands, add mouse modes and file readers that you
develop.  In addition to executing Python files in the directory, the startup directory will
be appended to the Python sys.path search path so Python modules in the subdirectory can be
imported.  Subdirectories in the startup directory that contain an __init__.py file will be
imported and if they contain a function named "start" it will be called with session as
an argument.

To use a directory other than ~/chimerax_start as the startup directory set the environment
variable CHIMERAX_START to the desired directory in the shell where Chimera is started.

Initializing the Session
========================

A :py:class:`~chimerax.core.session.Session` instance is passed as an
argument to many functions.
It is the way to access per-session data.
Leaf functions frequently are only given one attribute (or none at all).

``session.debug``
    True if debugging.

``session.logger``
    A :py:class:`~chimerax.core.logger.Log` instance to log errors to.

``session.app_dirs``
    A versioned :py:class:`~appdirs.AppDirs` instance with directories
    to look for application and user files in.

``session.app_dirs_unversioned``
    An unversioned :py:class:`~appdirs.AppDirs` instance with directories
    to look for application and user files in.

``session.app_data_dir``
    The location of "share" directory.

``session.ui``
    A :py:class:`~chimerax.core.logger.Log` instance.

``session.toolshed``
    A :py:class:`~chimerax.core.toolshed.Toolshed` instance.

``session.tools``
    A :py:class:`~chimerax.core.tools.Tools` instance.

``session.tasks``
    A :py:class:`~chimerax.core.tasks.Tasks` instance.

Other initial sessiona attributes are initialized in :py:func:`chimerax.core.session.common_startup`.