# README for libtime project, last updated February 3, 2024.

Libtime is a package of subroutines for the manipulation of time values.
The subroutines handle leap seconds correctly by avoiding the use of
POSIX time_t for telling time.

Notes to those who write software that calls libtime subroutines:

If you are using the Fedora distribution of GNU/Linux, the simplest way
to install libtime is from Fedora Copr:

    sudo dnf copr enable johnsauter/libtime

and respond "y" when it asks if you are sure.  When that is complete,
install the project:

    sudo dnf install libtime

With this method the library will be updated automatically whenever the
list of leap seconds changes.

If you are not running Fedora, or you prefer not to use Copr, you can
clone the project from github, then build and install the software.
Navigate to a convenient place in the file system of your computer
and clone the project:

    git clone git@github.com:ShowControl/libtime

then build and install the library:

  cd libtime
  ./configure --prefix=/usr
  make
  sudo make install

I recommend using --prefix=/usr on the ./configure command so the library
will be installed in /usr/share.  If you omit the --prefix=/usr, the
library will be installed in /usr/local/share.

If you do not have access to github but you do have the documentation PDF
file avoid_time_t.pdf, you can extract the files necessary to build
the tarball from the PDF.  In a convenient place in the file system of
your computer, create a directory named libtime, copy the avoid_time_t.pdf
file into it, then build and install the library:

    mkdir libtime
    cp avoid_time_t.pdf libtime/
    cd libtime/
    mkdir examples m4 src tests
    pdfdetach -saveall avoid_time_t.pdf
    bash fix_files.sh
    ./configure --prefix=/usr
    make
    sudo make install
    
Once the library is installed, in your C source code define the entry points
with:

    #include <time_subroutines.h>

When compiling and linking your program with GCC, specify -ltime.

If you installed libtime in /usr/local/share rather than /usr/share,
compile and link your program prog.c as follows:

    gcc -L/usr/local/lib/ -Wl,-rpath=/usr/local/lib prog.c -ltime -o prog

In your Python source code, define the entry points with:

   import time_subroutines
   
For installation from a repository, libtime is divided into three RPMs:
libtime for those who run programs that call libtime, libtime-devel for
those who write programs that call libtime, and libtime-doc, which contains
the comprehensive documentation for libtime.

Comprehensive documentation for the time subroutines is in avoid_time_t.pdf.
If you install libtime-doc from an RPM repository this will be in
/usr/share/doc/libtime-doc/.  If you are installing by cloning the
github repository you can create the PDF by adding --enable-pdf to the
./configure line before running make, or by doing a second run of make with
make pdf.  You will need LuaLaTeX and many of its packages to compile the PDF.
Sudo make install will then install the file in /usr/local/share/doc/libtime/.

If it is not convenient to compile the documentation, it is also available
at this URL:

https://www.systemeyescomputerstore.com/leap_seconds/avoid_time_t.pdf

In addition, there is concise documentation in man libtime.


Notes to anyone who wishes to maintain libtime:

To create the documentation file, invoke ./configure with --enable-pdf.
You will need LuaLaTeX to build it.  Building the distribution kit builds
the PDF automatically.  For the convenience of those who write programs
that call the libtime subroutines, the documentation is also kept at this
URL:

https://www.systemeyescomputerstore.com/leap_seconds/avoid_time_t.pdf

The version number of libtime is the distribution date, since the
unpredictability of leap seconds means the library will never be finished.
When updating the version number in configure.ac, don't forget to update
the sharable image version triplet, which is in configure.ac, NEWS and
the revision history section of avoid_time_t.tex.  If you make a change
to libtime that is not backwards-compatible, you will also have to
change the spec file.  Such changes are discouraged because they
require modifying potentially all the software that depends on libtime.

The date also appears in avoid_time_t.tex, in three places: in the
PDF metadata, on the title page, and in the revision history.  The date
is also in file references.bib, so other documents can refer to the
current version.  That file is alse used by "Extending Coordinated
Universal Time to Dates Before 1972", at this URL:

https://www.systemeyescomputerstore.com/leap_seconds/proleptic_UTC.pdf

That document is the source for the leap seconds table, which is built
from file extraordinary_days.dat.  The sources for that document are embedded
in its PDF, as are the sources for libtime embedded in avoid_time_t.pdf.

There are several test program in the distribution kit, which are built
automatically.  I use test_ep to be sure all of the entry points are
working.  To verify that the distribution kit is valid, I use
make distcheck and I also extract all of the embedded files from the PDF
into a clean directory and make sure the result builds.

On platforms without a C compiler that implements 128-bit integers, a subset
library is provided, omitting int128_to_string and time_tm_nano_to_integer.
If you are cross-compiling you will need to tell the configure script
whether or not the target computer has support for 128-bit integers.

I have not tried to port libtime to the Ubuntu distribution of GNU/Linux,
but Alien seems to create reasonable .deb files from the libtime, libtime-devel
and libtime-doc RPMs.

If this is the first change you are making to libtime since taking it over
from the previous maintainer, you should add your PGP public key to the
tarball and the PDF.  See John_Sauter_public_key.asc in Makefile.am
and avoid_time_t.tex for an example.

Here is the checklist I use to be sure I am distributing working software.
I start with proleptic_utc_with_leap_seconds and libtime installed, and in the
directory which is a clone of the github repository.

1. Perform whatever updates are called for to the libtime sources.  If you are
just rebuilding libtime because proleptic_utc_with_leap_seconds changed,
no changes to the source code are required.

2. Edit file configure.ac to set the version number to the expected
distribution date, and update the version-info triplet.  There are comments in
configure.ac explaining the version-info triplet.

3. Edit file libtime.spec to set the version number to the value in
configure.ac and add an entry to the revision history.  If the only reason
we are updating libtime is because proleptic_utc_with_leap_seconds changed,
use the same comment as in that package's spec file.

4. Edit file NEWS to add the new version number, the new version-info
triplet, and the reason for the update.

5. Edit file avoid_time_t.tex to update the revision date on the title
page and in the PDF metadata.  Update the revision history using the
information in the NEWS file.

6. Get rid of old files with wrong version numbers in their names:
   rm *.gz
   rm *.rpm

7. Edit reference.bib to update the publication date of "Avoid Using POSIX
time_t for Telling Time".  This is the documentation for the project,
which you will be publishing as part of updating the project.  This file
should be centralized so that every publication gets the latest copy,
but I haven't figured out a way to do this yet.
   
8. Build and test the libtime tarball.  In the following commands,
/usr is the prefix of the location of the data file provided by
proleptic_utc_with_leap_seconds.  The commands should all run without error.
   
     ./autogen.sh --download
     ./configure --prefix=/usr
     make
     make pdf
     make check
     make dist
     make distcheck
     make signature
     gpg --verify libtime*.asc libtime*.tar.gz

That last step should declare that the tarball has a good signature.
You will use that signature later to verify that the tarball has
not been accidently corrupted.

9. Use evince to verify that avoid_time_t.pdf has the correct date
on its cover page, the revision history has been updated and the
pagination looks OK.

10. Create and test the SRPM file.  RPMlint will complain
that the -doc RPM has no binaries.  It may also complain about the spelling
of "tm".  Anything else needs to be investigated.
This is the first step that tests the spec file.  If you need to change it
go back to the autogen step, since the spec file is included in the tarball.

   make RPMs

11. Make sure the tarball will build from the PDF:  All of these commands
should run without error.  The autogen command is at the end instead of
before configure since configure is supposed to work without first
running autogen, but autogen should still work.

    mkdir test_pdf
    cp avoid_time_t.pdf test_pdf/
    cd test_pdf/
    mkdir examples m4 src tests
    pdfdetach -saveall avoid_time_t.pdf
    bash fix_files.sh
    ./configure --prefix=/usr
    make
    make check
    make pdf
    make dist
    make distcheck
    make RPMs
    ./autogen.sh --download

12. We are done with the test_pdf subdirectory:

    cd ..
    rm -r test_pdf/
    
13. Use an internet browser to log in to the Fedora Copr web site.
Navigate to project libtime.  Make sure it is configured to build
the package on all platforms.

14. Attempt to build libtime on lots of different platforms using Copr:

    copr-cli build libtime libtime-*.src.rpm

This will build libtime on your Copr account, which means you should direct
Copr users to your repository rather than mine.  If you would like to use my
Copr repository you will need permission.  Log in to Fedora Copr, then
navigate to this project's overview at

    https://copr.fedorainfracloud.org/coprs/johnsauter/libtime/

choose Settings, click on the types of permissions you want, and click on
Request.  Please contact me first so the request won't come at me out of
the blue.  My e-mail address is John_Sauter@systemeyescomputerstore.com.

After you have permission, to build into my Copr repository:

    copr-cli build johnsauter/libtime libtime-*.src.rpm
    

15. When the build is finished, check the Copr web site to see if it
succeeded on all of the important platforms.  If the build has failed on any
important platforms, correct any problems to the best of your ability
and re-run the build until the only errors left are due to the Copr
infrastructure.  If you have to modify any of the files, return to the autogen
step.

16. You may be forced to declare certain formerly important platforms as
unimportant if they refuse to build the package for no good reason.

17. Delete the old builds and regenerate the repositories.

18. Wait a few minutes for the repository mirrors to receive the new
code, then type the following to make sure the new version is avaialble:

    sudo dnf update --refresh

19. If you have a web site from which you make available the current version
of avoid_time_t.pdf, copy the file to the web site now, since it will be
deleted from this directory in the next step.

20. Update the sources on github:

    make distclean
    git add .
    git commit -a -m "<comment>"
    git tag -s "<version>" -m "<comment>"
    git push
    git push --tags

The notation <comment> means a brief description of the change.
If you are rebuilding libtime just because proleptic_utc_with_leap_seconds
changed, use the same comment that you used in that project.
For example, "Adjust future leap seconds starting in 2499."
The notation <version> means the version number as recorded in the
spec file and elsewhere.
    
21. Verify that the tarball has not been corrupted:

    gpg --verify libtime*.asc libtime*.tar.gz

Gpg should declare  that the tarball has a good signature.  If it does not
go back to the autogen step to re-create it.  You will not have to edit 
any files.


Notes to those who wish to package libtime in a distribution of GNU/Linux:

The tarball lives on github at ShowControl/libtime.  It gets its table
of leap seconds from file extraordinary_days.dat, which is provided by
package proleptic_utc_with_leap_seconds, which lives on github at
ShowControl/proleptic_utc_with_leap_seconds.  The tarball includes
a spec file which lists its dependencies.  I use that spec file
to build the package on Copr.  I would be happy to include any
modifications you make to the spec file in the tarball.

End of file README