1This is the source code repository for ERFA (Essential Routines for
2Fundamental Astronomy).  ERFA is a C library containing key algorithms for
3astronomy, and is based on the `SOFA library <http://www.iausofa.org/>`_ published by the International
4Astronomical Union (IAU).
5
6ERFA is intended to replicate the functionality of SOFA (aside from possible
7bugfixes in ERFA that have not yet been included in SOFA), but is licensed
8under a three-clause BSD license to enable its compatibility with a wide
9range of open source licenses. Permission for this release has been
10obtained from the SOFA board, and is avilable in the ``LICENSE`` file included
11in this source distribution.
12
13Differences from SOFA
14---------------------
15
16This version of ERFA (v1.1.0) is based on SOFA version "20131202_b", with the
17differences outlined below.
18
19ERFA branding
20^^^^^^^^^^^^^
21
22All references to "SOFA" in the source code have been changed to ERFA, and
23functions have the prefix ``era`` instead of ``iau``.
24
25C macro prefixes
26^^^^^^^^^^^^^^^^
27
28All C macros used in ERFA are the same as their SOFA equivalents, but with an
29``ERFA_`` prefix to prevent namespace collisions.
30
31Building and installing ERFA
32----------------------------
33
34To build and install a released version of ERFA in your OS's standard
35location, simply do::
36
37    ./configure
38    make
39    make install
40
41If you want to run the tests to make sure ERFA built correctly, before
42installing do::
43
44    make check
45
46
47For developers
48^^^^^^^^^^^^^^
49
50If you are using a developer version from github, you will need to first do
51``./bootstrap.sh`` before the above commands. This requires ``autoconf`` and
52``libtool``.
53
54If you wish to build against the ERFA static library without installing, you
55will find it in ``$ERFAROOT/src/.libs/liberfa.a`` after running ``make``.
56
57Creating a single-file version of the source code
58^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59
60Alternatively, if you wish to bundle the ERFA source code with a separate
61package, you can use the ``source_flattener.py`` script from the
62`erfa-fetch repository`_ to combine
63the ERFA source code into just two files: a ``erfa.c`` source file, and an
64``erfa.h`` include file.  You should run this script like this::
65
66    cd /path/to/erfa-source-code
67    python /path/to/erfa-fetch/source_flattener.py src -n erfa
68
69If possible, however, it is recommended that you provide an option to use any
70copy of the ERFA library that is already installed on the system.
71
72Travis build status
73-------------------
74.. image:: https://travis-ci.org/liberfa/erfa.png
75    :target: https://travis-ci.org/liberfa/erfa
76
77.. _erfa-fetch repository: https://github.com/liberfa/erfa-fetch
78