Added FORD manifest.

Author: interkosmos

Makefile

@@ -9,6 +9,7 @@
 #   CC      - C compiler.
 #   AR      - Archiver.
 #   MAKE    - Make tool.
+#   FORD    - FORD documentation generator.
 #   FFLAGS  - Fortran compiler flags.
 #   CFLAGS  - C compiler flags.
 #   PPFLAGS - Pre-processor flags. Change to `-fpp` for Intel IFORT.
@@ -23,6 +24,7 @@ FC      = gfortran
 CC      = gcc
 AR      = ar
 MAKE    = make
+FORD    = ford
 
 DEBUG   = -g -O0 -Wall -fmax-errors=1
 RELEASE = -O2 -march=native
@@ -35,6 +37,7 @@ LDFLAGS = -I$(PREFIX)/include -L$(PREFIX)/lib
 LDLIBS  =
 INCDIR  = $(PREFIX)/include/libfortran-unix
 LIBDIR  = $(PREFIX)/lib
+DOCDIR  = ./doc
 
 TARGET  = libfortran-unix.a
 
@@ -55,9 +58,13 @@ OBJ = unix.o unix_dirent.o unix_errno.o unix_fcntl.o \
       unix_time.o unix_types.o unix_unistd.o unix_utsname.o \
       unix_wait.o unix_macro.o
 
-.PHONY: all clean examples freebsd freebsd_examples install linux linux_examples
+.PHONY: all clean doc examples install \
+        freebsd freebsd_doc freebsd_examples \
+        linux linux_doc linux_examples
 
-all: $(TARGET)
+all:
+	@echo "Add build target [freebsd|linux], for example:"
+	@echo "make linux"
 
 # Library
 $(TARGET): $(SRC)
@@ -169,6 +176,17 @@ uname: $(TARGET) examples/uname/uname.f90
 uptime: $(TARGET) examples/uptime/uptime.f90
 	$(FC) $(FFLAGS) $(PPFLAGS) $(LDFLAGS) -o uptime examples/uptime/uptime.f90 $(TARGET) $(LDLIBS)
 
+# Documentation
+doc: ford.md
+	$(FORD) -d ./src ford.md
+
+freebsd_doc: ford.md
+	$(FORD) -m "__FreeBSD__" -d ./src ford.md
+
+linux_doc: ford.md
+	$(FORD) -m "__linux__" -d ./src ford.md
+
+# Installation.
 install: $(TARGET)
 	@echo "--- Installing $(TARGET) to $(LIBDIR)/ ..."
 	install -d $(LIBDIR)
@@ -177,9 +195,11 @@ install: $(TARGET)
 	install -d $(INCDIR)
 	install -m 644 unix*.mod $(INCDIR)/
 
+# Clean-up.
 clean:
 	if [ `ls -1 *.mod 2>/dev/null | wc -l` -gt 0 ]; then rm *.mod; fi
 	if [ `ls -1 *.o 2>/dev/null | wc -l` -gt 0 ]; then rm *.o; fi
+	if [ -e $(DOCDIR) ]; then rm -r $(DOCDIR); fi
 	if [ -e $(TARGET) ]; then rm $(TARGET); fi
 	if [ -e dirent ]; then rm dirent; fi
 	if [ -e fifo ]; then rm fifo; fi

README.md

@@ -94,6 +94,31 @@ On Linux:
 $ fpm build --profile release --flag "-D__linux__"
 ```
 
+## Source Code Documentation
+
+The source code documentation of the library has to be created with
+[FORD](https://github.com/Fortran-FOSS-Programmers/ford). Install the Python
+package with:
+
+```
+$ python3 -m pip install -U ford
+```
+
+In the source repository, either run:
+
+```
+$ make freebsd_doc
+```
+
+Or:
+
+```
+$ make linux_doc
+```
+
+The HTML files will be written to directory `doc/`. Open `index.html` in a web
+browser.
+
 ## Examples
 
 Examples are provided in directory `examples/`:

ford.md

@@ -0,0 +1,84 @@
+project:        fortran-unix
+version:        0.1.0
+license:        isc
+doc_license:    by
+graph:          false
+search:         true
+display:        public
+sort:           alpha
+fpp_extensions: F90
+macro:          __linux__
+preprocess:     true
+summary:        **fortran-unix** – A collection of Fortran 2008 ISO C binding
+                interfaces to selected POSIX and SysV types, functions, and
+                routines on 64-bit Linux and FreeBSD.
+author:         Philipp Engel
+project_github: https://github.com/interkosmos/fortran-unix
+
+The library covers system calls for:
+
+* standard input/output,
+* file and directory access,
+* clocks and timers,
+* signals,
+* processes,
+* pipes,
+* serial port input/output,
+* terminal control,
+* POSIX threads,
+* POSIX mutexes and semaphores,
+* POSIX regular expressions,
+* BSD sockets,
+* UNIX System V message queues,
+* POSIX message queues.
+
+By default, the documentation is based on the Linux API. For the FreeBSD API,
+select build target `freebsd_doc`:
+
+```
+$ make freebsd_doc
+```
+
+## Build Instructions
+
+On Linux, run:
+
+```
+$ make linux
+```
+
+On FreeBSD, run:
+
+```
+$ make freebsd
+```
+
+To compile with Intel oneAPI instead of GCC:
+
+```
+$ make CC=icx FC=ifx PPFLAGS=
+```
+
+Optionally, install `libfortran-unix.a` and the associated module files
+system-wide:
+
+```
+$ make install PREFIX=/opt
+--- Installing libfortran-unix.a to /opt/lib/ ...
+--- Installing module files to /opt/include/libfortran-unix/ ...
+```
+
+## Fortran Package Manager
+
+Using the Fortran Package Manager, a preprocessor flag has to be passed to GNU
+Fortran. On Linux:
+
+```
+$ fpm build --profile release --flag "-D__linux__"
+```
+
+On FreeBSD:
+
+```
+$ fpm build --profile release --flag "-D__FreeBSD__"
+```