The MagAOX Software System
This is the software which runs the MagAOX ExAO system.
- mxlib (https://github.com/jaredmales/mxlib).
For a MagAO-X machine change the prefix to
/usr/localin the mxlib install
- libudev (for introspective device discovery). Get from package manager.
- zlib (compression for INDI). Get from package manager:
- zlib-devel [centOS-7]
- zlib1g-dev [ubuntu]
- flatbuffers (https://google.github.io/flatbuffers/flatbuffers_guide_building.html)
To build and install the flatc compiler and install the include files in /usr/local:
$ cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release $ make $ sudo make install
2 Software Configuration
For a standard build, nothing needs to be done here. However, various defaults can be changed with macros. To override at build time, the following macros can be redefined in
2.1 Environment Variables
These are defined in
libMagAOX/common/environment.hpp. They do not need to be set, but can be used to override relevant defaults.
MAGAOX_env_path, the name of the environment variable holding the base path to the MagAOX system directories. Default = "MagAOX_PATH"
MAGAOX_env_config, the name of the environment variable holding the relative path to the config files. Default = "MagAOX_CONFIG".
2.2 Default Values
These are values which might be changed for different components. These are defined in
libMagAOX/common/defaults.hpp. They do not normally need to be changed, but these macros can be used to override relevant defaults.
2.3 Config Values
These are values which should change for all components of MagAO-X. These are defined in
libMagAOX/common/config.hpp. They do not normally need to be changed for a typical build, but these macros can be used to override relevant defaults.
MAGAOX_RT_SCHED_POLICY is the real-time scheduling policy. The result is
These are defined in
libMagAOX/common/paths.hpp. They do not normally need to be changed, but these macros can be used to override the relevant defaults.
MAGAOX_pathThe path to the MagAO-X system files This directory will have subdirectories including config, log, and sys directories.
MAGAOX_configRelPathThis is the subdirectory for configuration files.
MAGAOX_globalConfigThe filename for the global configuration file. Will be looked for in the config/ subdirectory.
MAGAOX_logRelPathThis is the subdirectory for logs.
MAGAOX_sysRelPathThis is the subdirectory for the system status files.
MAGAOX_secretsRelPathThis is the subdirectory for secrets.
MAGAOX_driverRelPathThis is the subdirectory for the INDI drivers.
MAGAOX_driverFIFORelPathThis is the subdirectory for the INDI driver FIFOs.
A rudimentary build system has been implemented.
To build an app, cd to the app's directory and type
make -f ../../Make/magAOXApp.mk t=<appname>
appname with the name of the application.
To build a utility, cd to the utility's directory and type
make -f ../../Make/magAOXUtil.mk t=<utilname>
utilname with the name of the utility.
The difference between the two Makefiles is in install, in that MagAO-X Applications get setuid, whereas the utilities do not.
libMagAOX (part of this repository) is a c++ header-only library. It is compiled into a pre-compiled-header (PCH), managed by the build system. Any changes to libMagAOX should trigger a re-compile of the PCH, and of any apps depending on it.
Allowing setuid for RT priority handling, access to ttys and FIFOs, etc., requires hardcoding LD_LIBRARY_PATH at build time. This is done in the makefiles, and so should be transparent.
Install requires root privileges.
-  Use environment variables for path to various parts of build system, path to libMagAOX PCH, etc.
-  Possibly use name of directory for target app name.
4 Software Install
The software install process (from BIOS setup to building the MagAO-X software) is described in detail in setup/README.md. To the extent practicable, this is automated by the scripts in
setup/ that take over after CentOS is installed.
The following are the default MagAOX system directories.
||MagAOX system directory|
||Contains all applications|
||Contains the configuration files for the applications|
||Directory where logs are written by the applications (chown :magaox, mode g+rws)|
||Directory for application status files, e.g. PID lock-files|
||Directory containing device passwords, etc.|
This directory structure is #define-ed in libMagAOX/common/defaults.hpp. It is created by the script
setup/make_directories.sh (except for
config, which is made by cloning magao-x/config into
/opt/MagAOX/config). Permissions are set in
setup/set_permissions.sh. This structure is also specified in
local/config.mk. Changing this isn't yet very simple, but we intend for it to be possible to have parallel installations.
- Investigate using appropriate environment variables to allow overriding these.
- Investigate having the defines be passed in via make. E.g.
-DMAGAOX_path=/opt/MagAOX-DEVwill override, maybe we should just inherit from
On install, symlinks are made for executables from
The code is more-or-less carefully documented with doxygen
-  Complete doxygen doc system
-  Script construction of complete docs from various places (doxygen, and the markdown app docs)
-  Create system to automatically make c.l. option table for each app
-  Decide: do we use github pages, or host it on one of the snazzy magao-x domains?
To-do items are listed in the above sections. Also see the Todo page in the doxygen html. Other misc. items below:
-  split base INDI off into separate repo, which will be the minimum someone needs to have INDI utils for interacting with MagAO-X without installing the whole tree.
-  create indiserver startup script which takes a list of drivers from a config file, creates symlinks to xindidriver as needed, and then starts indiserver itself.
-  start issue tracking
The MagAOX code is intimately tied to Linux OS internals, and targets CentOS 7 for the realtime control computers. To develop in the most "flight-like" configuration, a Vagrantfile is provided to set up a development VM.
After cloning the MagAOX repository,
cd into it and run
vagrant up. Provisioning uses the
setup/vagrant_provision.sh script, which in turn calls other scripts in
setup/ and sets permissions. Provisioning is slow (~ 10s of minutes), but only costly the first time you start the VM. Vagrant will download a virtual machine image for CentOS 7 and then set up all the dependencies required. NFS is used to sync the contents of your repository clone to the VM.
To connect to the VM, use
vagrant ssh. The VM has a view of your copy of this repository under
/vagrant. For example, no matter where you cloned this repository on your own (host) machine, the virtual machine will see this file at
/vagrant/README.md. (For consistency with production, we symlink
/vagrant.) Edits to the MagAO-X software source on your computer will be instantly reflected on the VM side, ready for you to
vagrant user you log in as will be a member of the
magaox-dev groups, and should have all the necessary permissions to run the system (or, at least, the parts you can run in a VM).