# System routines

These functions are declared in the main Allegro header file:

~~~~c
 #include <allegro5/allegro.h>
~~~~

## API: al_install_system

Initialize the Allegro system. No other Allegro functions can be called
before this (with one or two exceptions).

The version field should always be set to ALLEGRO_VERSION_INT.

If atexit_ptr is non-NULL, and if hasn't been done already,
[al_uninstall_system] will be registered as an atexit
function.

Returns true if Allegro was successfully initialized by this function
call (or already was initialized previously), false if Allegro cannot
be used. A common reason for this function to fail is when the version of
Allegro you compiled your game against is not compatible with the version of
the shared libraries that were found on the system.

The version compatibility check works as follows. Let A = xa.ya.za.* be the
version of Allegro you  compiled with, and B = xb.yb.zb.* be the version of
Allegro found in the system shared library.

If you defined `ALLEGRO_UNSTABLE` before including Allegro headers, then
version A is compatible with B only if xa.ya.za = xb.yb.zb. Otherwise, A is
compatible with B only if xa.ya = xb.yb.

See also: [al_init]

## API: al_init

Like [al_install_system], but automatically passes in the version and uses the
atexit function visible in the current binary.

> Note: It is typically wrong to call al_init anywhere except the final game
binary. In particular, do not call it inside a shared library unless you know
what you're doing. In those cases, it is better to call al_install_system
either with a `NULL` atexit_ptr, or with a pointer to atexit provided by the
user of this shared library.

See also: [al_install_system]

## API: al_uninstall_system

Closes down the Allegro system.

> Note: al_uninstall_system() can be called without a corresponding
[al_install_system] call, e.g. from atexit().

## API: al_is_system_installed

Returns true if Allegro is initialized, otherwise returns false.

## API: al_get_allegro_version

Returns the (compiled) version of the Allegro library, packed into a single
integer as groups of 8 bits in the form
`(major << 24) | (minor << 16) | (revision << 8) | release`.

You can use code like this to extract them:

~~~~c
uint32_t version = al_get_allegro_version();
int major = version >> 24;
int minor = (version >> 16) & 255;
int revision = (version >> 8) & 255;
int release = version & 255;
~~~~

The `release` number is 0 for an unofficial version and 1 or greater for
an official release. For example "5.0.2[1]" would be the (first) official
5.0.2 release while "5.0.2[0]" would be a compile of a version from the
"5.0.2" branch before the official release.

## API: al_get_standard_path

Gets a system path, depending on the `id` parameter. Some of these paths
may be affected by the organization and application name, so be sure to
set those before calling this function.

The paths are not guaranteed to be unique (e.g., SETTINGS and DATA may be
the same on some platforms), so you should be sure your filenames are unique
if you need to avoid naming collisions. Also, a returned path may not actually
exist on the file system.

ALLEGRO_RESOURCES_PATH
:   If you bundle data in a location relative to your executable, then you
    should use this path to locate that data. On most platforms, this is the
    directory that contains the executable file. 
    
    If called from an OS X app bundle, then this will point to the internal
    resource directory (<bundle.app>/Contents/Resources). To maintain 
    consistency, if you put your resources into a directory called "data"
    beneath the executable on some other platform (like Windows), then
    you should also create a directory called "data" under the OS X app
    bundle's resource folder.
    
    You should not try to write to this path, as it is very likely read-only.
    
    If you install your resources in some other system directory (e.g., in
    /usr/share or C:\\ProgramData), then you are responsible for keeping track
    of that yourself.    
    
ALLEGRO_TEMP_PATH
:   Path to the directory for temporary files.

ALLEGRO_USER_HOME_PATH
:   This is the user's home directory. You should not normally write files into
    this directory directly, or create any sub folders in it, without explicit
    permission from the user.  One practical application of this path
    would be to use it as the starting place of a file selector in a GUI.
    
ALLEGRO_USER_DOCUMENTS_PATH
:   This location is easily accessible by the user, and is the place
    to store documents and files that the user might want to later open with
    an external program or transfer to another place. 
    
    You should not save files here unless the user expects it, usually by
    explicit permission.

ALLEGRO_USER_DATA_PATH
:   If your program saves any data that the user doesn't need to access 
    externally, then you should place it here. This is generally the least
    intrusive place to store data. This path will usually not be present on the
    file system, so make sure to create it before writing to it.
    
ALLEGRO_USER_SETTINGS_PATH
:   If you are saving configuration files (especially if the user may want to
    edit them outside of your program), then you should place them here. This
    path will usually not be present on the file system, so make sure to create
    it before writing to it.
    
ALLEGRO_EXENAME_PATH
:   The full path to the executable.

Returns NULL on failure.  The returned path should be freed with
[al_destroy_path].

See also: [al_set_app_name], [al_set_org_name], [al_destroy_path], [al_set_exe_name]

## API: al_set_exe_name

This override the executable name used by [al_get_standard_path] for
ALLEGRO_EXENAME_PATH and ALLEGRO_RESOURCES_PATH.

One possibility where changing this can be useful is if you use the
Python wrapper. Allegro would then by default think that the system's
Python executable is the current executable - but you can set it to
the .py file being executed instead.

Since: 5.0.6, 5.1.0

See also: [al_get_standard_path]

## API: al_set_app_name

Sets the global application name.

The application name is used by [al_get_standard_path] to build the full path to
an application's files.

This function may be called before [al_init] or [al_install_system].

See also: [al_get_app_name], [al_set_org_name]

## API: al_set_org_name

Sets the global organization name.

The organization name is used by [al_get_standard_path] to build the full path to
an application's files.

This function may be called before [al_init] or [al_install_system].

See also: [al_get_org_name], [al_set_app_name]

## API: al_get_app_name

Returns the global application name string.

See also: [al_set_app_name]

## API: al_get_org_name

Returns the global organization name string.

See also: [al_set_org_name]

## API: al_get_system_config

Returns the system configuration structure. The returned configuration should
not be destroyed with [al_destroy_config]. This is mainly used for configuring
Allegro and its addons. You may populate this configuration before Allegro is
installed to control things like the logging levels and other features.

Allegro will try to populate this configuration by loading a configuration file
from a few different locations, in this order:

- *Unix only:* /etc/allegro5rc

- *Unix only:* $HOME/allegro5rc

- *Unix only:* $HOME/.allegro5rc

- allegro5.cfg next to the executable

If multiple copies are found, then they are merged using [al_merge_config_into].

The contents of this file are documented inside a prototypical `allegro5.cfg`
that you can find in the root directory of the source distributions of Allegro.
They are also reproduced below.

Note that Allegro will not look into that file unless you make a copy of it and
place it next to your executable!

~~~~ini
__ALLEGRO_5_CFG
~~~~

## API: al_register_assert_handler

Register a function to be called when an internal Allegro assertion fails.
Pass NULL to reset to the default behaviour, which is to do whatever the
standard `assert()` macro does.

Since: 5.0.6, 5.1.0

## API: al_register_trace_handler

Register a callback which is called whenever Allegro writes something to its
log files. The default logging to allegro.log is disabled while this callback
is active. Pass NULL to revert to the default logging.

This function may be called prior to al_install_system.

See the example allegro5.cfg for documentation on how to configure the used
debug channels, logging levels and trace format.

Since: 5.1.5

## API: al_get_cpu_count

Returns the number of CPU cores that the system Allegro is running on
has and which could be detected, or a negative number if detection failed. 
Even if a positive number is returned, it might be that it is not correct.
For example, Allegro running on a virtual machine will return the amount of
CPU's of the VM, and not that of the underlying system. 

Furthermore even if the number is correct, this only gives you information about 
the total CPU cores of the system Allegro runs on. The amount of cores available 
to your program may be less due to circumstances such as programs that are 
currently running.


Therefore, it's best to use this for advisory purposes only. It is certainly a 
bad idea to make your program exclusive to systems for which this function 
returns a certain "desirable" number.

This function may be called prior to [al_install_system] or [al_init].

Since: 5.1.12

## API: al_get_ram_size

Returns the size in MB of the random access memory that the system Allegro is 
running on has and which could be detected, or a negative number if detection 
failed. Even if a positive number is returned, it might be that it is not 
correct. For example, Allegro running on a virtual machine will return 
the amount of RAM of the VM, and not that of the underlying system. 

Furthermore even if the number is correct, this only gives you information about 
the total physical memory of the system Allegro runs on. The memory available 
to your program may be less or more than what this function returns due to
circumstances such as virtual memory, and other programs that are currently 
running.

Therefore, it's best to use this for advisory purposes only. It is certainly a 
bad idea to make your program exclusive to systems for which this function 
returns a certain "desirable" number.

This function may be called prior to [al_install_system] or [al_init].

Since: 5.1.12
