gnucap-custom provides a basis for gnucap customisations including stuff and
work in progress that I find useful.

== gnucap-custom (the binary)

an executable allowing for easy customisation. This replaces the
upstream gnucap executable in some situations.

 options are (some are subject to plugins)
   -v file.v          # process verilog file
   -DXXX, -UXXX       # "`define XXX", "`undef XXX"
   -I/path/to/stuff   # append to `include path

== 'gncp'. out of the box example

this is just a symlink to gnucap-custom, and a corresponding rc.
it has all available features enabled.

- readline persistent history
- make transitive relative includes work
- GNUCAP_INCLUDEPATH environment controls `include
- (partial) verilog preprocessing, `if(n)def etc.
- load .cc files directly (compile on demand).

== plugins

most functionality is provided as plugins, and extends libgnucap. It can be
used from whichever gnucap program, e.g.

$ gnucap -a custom/c_include.so       # provides `include command
$ gnucap -a custom/tab_completion.so  # enables tab_completion
$ gnucap -a custom/c_cmk.so           # node ordering
$ gnucap -a custom/c_make_attach.so   # build and load plugins in 1 go
(etc.)

== creating custom executables

gnucap loads $sysconfdir/basename(argv[0]).rc upon startup. it takes
GNUCAP_SYSCONFDIR (if specified) from the environment as an override for
$sysconfdir.

now its possible to have local custom installations.
$ export GNUCAP_SYSCONFDIR=$HOME/.gnucap:/etc    # put in ~/.profile?
$ echo stuff > $HOME/.gnucap/foocap.rc           # configure something
$ ln -s  /usr/bin/gnucap $HOME/.bin/foocap       # or wherever it is.
$ foocap                                         # reads stuff
your-own-flavour> ...

== installation

you need to install gnucap-custom (the binary) so this works without
additional environment tweaks (recommended).

see INSTALL for instructions

== TODO/WIP

- -b is still missing (and other slight deviations)
- per directory rc
- undef-all/reset command (hook into clear)
- verilog `constant expansion
- exit codes (fix exception handling)

== BUGS/LIMITATIONS

- lang_vpp:
 - not sure if verilog has `if 0/1
 - requires patched lang_verilog
 - preprocessor conditionals must be aligned to scopes.
- tab_completion: needs work.