Riwux core
+============+

The rcore project aims to provide a minimal but complete commandline
environment containing utilities found on most UNIX(-like) systems.
It's goal is to be simple, portable and compliant while still being pleasant
to use. Features and extensions are chosen carefully and only implemented if
they are either (very) common or provide real value to the user.


  Modules
+=========+

rcore is split into several different subdirectories (i.e modules),
each dedicated to a specific standard or group of utilities.
This adds the possibility to exclude certain tools (e.g. linux/ on BSD systems)
or only select a small subset to be replaced on an already existing system.

posix/ -- POSIX.1-2017 utilities
more/  -- common non-standard utilities
linux/ -- non-portable Linux specific utilities


  Build
+=======+

rcore requires a compiler that implements ISO C99, a libc that conforms to
POSIX.1-2008 and ISO C99 as well as a make(1) implementation that is
POSIX.1-2008 compliant and supports <slash>'es in target names.
To build rcore, follow these instructions:

    $ make            # build the whole project
    $ make all        # same as above

    $ make install    # install utilities
    $ make uninstall  # uninstall utilities
    $ make clean      # remove all binaries and build leftovers

    $ make posix      # only build POSIX utilities
    $ make more       # only build non-standard / more utilities
    $ make linux      # only build Linux specific utilities

    $ make lib           # only build libraries (in lib/)
    $ make posix/src/cat # only build utility specified by the path (i.e. cat).
                         # It might be necessary to build lib/ first

In case you want to customize your build process, change the corresponding
values in config.mak or directly on the commandline.

Supported compilers:
   clang
    $ make CC=clang
   gcc
    $ make CC=gcc
   tcc
    $ make CC=tcc
   cproc
    $ make CC=cproc
   pcc
    $ make LDFLAGS='-L lib/libutil -lutil' CC=pcc


  Conventions
+=============+

* Error messages:

  It's important that error messages are consistent across all utilities
  since they form the base of a system and should feel coherent.
  The format is simple but does not hide any information. It should be
  possible to look at an error message and immediately know what happened.
  The format is specified as follows:


     <utility> [: <function> ['<argument>']] [: <message>]\n


  utility  : The name of the program.
  function : The function that reports the error.
  argument : The argument the function operates on (if any)
  message  : optional useful information (e.g. errno-string)



* Function names:

  Function names that are part of a library (i.e shared accross all tools)
  and have the potential to exit(3) the program are prefixed with 'x_'.
  Those functions local to a utility don't (have to) follow this convention.



* Options:

  Mutually exclusive options (e.g. [-a | -b]) can be specified together
  without resulting in an error. The last option specified is used/active
  while the options prior are ignored and have no effect.

    util -a -b -a -b -a -c

  In this example '-a' will be used by the program since it is the last
  out of the mutually exclusive options 'a' and 'b'. The normal option 'c'
  will be active regardless since it has no relationship with the other
  options.


  Long options are not implemented since they are non-standard and don't
  provide much value. Most of the time they just provide another, longer
  name for an already existing option. They complicate and confuse a program
  without adding functionality or anything useful.