Return to README.md CVS log

Up to [local] / src / usr.bin / awk

Annotation of src/usr.bin/awk/README.md, Revision 1.5

1.5     ! millert     1: $OpenBSD: README.md,v 1.4 2020/12/09 20:00:11 millert Exp $
1.1       millert     2:
                      3: # The One True Awk
                      4:
                      5: This is the version of `awk` described in _The AWK Programming Language_,
                      6: by Al Aho, Brian Kernighan, and Peter Weinberger
                      7: (Addison-Wesley, 1988, ISBN 0-201-07981-X).
                      8:
                      9: ## Copyright
                     10:
                     11: Copyright (C) Lucent Technologies 1997<br/>
                     12: All Rights Reserved
                     13:
                     14: Permission to use, copy, modify, and distribute this software and
                     15: its documentation for any purpose and without fee is hereby
                     16: granted, provided that the above copyright notice appear in all
                     17: copies and that both that the copyright notice and this
                     18: permission notice and warranty disclaimer appear in supporting
                     19: documentation, and that the name Lucent Technologies or any of
                     20: its entities not be used in advertising or publicity pertaining
                     21: to distribution of the software without specific, written prior
                     22: permission.
                     23:
                     24: LUCENT DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
                     25: INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
                     26: IN NO EVENT SHALL LUCENT OR ANY OF ITS ENTITIES BE LIABLE FOR ANY
                     27: SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     28: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
                     29: IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
                     30: ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
                     31: THIS SOFTWARE.
                     32:
                     33: ## Distribution and Reporting Problems
                     34:
                     35: Changes, mostly bug fixes and occasional enhancements, are listed
                     36: in `FIXES`.  If you distribute this code further, please please please
                     37: distribute `FIXES` with it.
                     38:
                     39: If you find errors, please report them
                     40: to bwk@cs.princeton.edu.
                     41: Please _also_ open an issue in the GitHub issue tracker, to make
                     42: it easy to track issues.
                     43: Thanks.
                     44:
                     45: ## Submitting Pull Requests
                     46:
1.2       millert    47: Pull requests are welcome. Some guidelines:
                     48:
                     49: * Please do not use functions or facilities that are not standard (e.g.,
                     50: `strlcpy()`, `fpurge()`).
                     51:
                     52: * Please run the test suite and make sure that your changes pass before
                     53: posting the pull request. To do so:
                     54:
                     55:   1. Save the previous version of `awk` somewhere in your path. Call it `nawk` (for example).
                     56:   1. Run `oldawk=nawk make check > check.out 2>&1`.
                     57:   1. Search for `BAD` or `error` in the result. In general, look over it manually to make sure there are no errors.
                     58:
                     59: * Please create the pull request with a request
1.1       millert    60: to merge into the `staging` branch instead of into the `master` branch.
                     61: This allows us to do testing, and to make any additional edits or changes
                     62: after the merge but before merging to `master`.
                     63:
                     64: ## Building
                     65:
                     66: The program itself is created by
                     67:
                     68:        make
                     69:
                     70: which should produce a sequence of messages roughly like this:
                     71:
                     72:        yacc -d awkgram.y
                     73:        conflicts: 43 shift/reduce, 85 reduce/reduce
                     74:        mv y.tab.c ytab.c
                     75:        mv y.tab.h ytab.h
                     76:        cc -c ytab.c
                     77:        cc -c b.c
                     78:        cc -c main.c
                     79:        cc -c parse.c
                     80:        cc maketab.c -o maketab
                     81:        ./maketab >proctab.c
                     82:        cc -c proctab.c
                     83:        cc -c tran.c
                     84:        cc -c lib.c
                     85:        cc -c run.c
                     86:        cc -c lex.c
                     87:        cc ytab.o b.o main.o parse.o proctab.o tran.o lib.o run.o lex.o -lm
                     88:
                     89: This produces an executable `a.out`; you will eventually want to
                     90: move this to some place like `/usr/bin/awk`.
                     91:
                     92: If your system does not have `yacc` or `bison` (the GNU
                     93: equivalent), you need to install one of them first.
                     94:
                     95: NOTE: This version uses ANSI C (C 99), as you should also.  We have
                     96: compiled this without any changes using `gcc -Wall` and/or local C
                     97: compilers on a variety of systems, but new systems or compilers
                     98: may raise some new complaint; reports of difficulties are
                     99: welcome.
                    100:
                    101: This compiles without change on Macintosh OS X using `gcc` and
                    102: the standard developer tools.
                    103:
1.4       millert   104: You can also use `make CC=g++` to build with the GNU C++ compiler,
                    105: should you choose to do so.
                    106:
1.1       millert   107: The version of `malloc` that comes with some systems is sometimes
                    108: astonishly slow.  If `awk` seems slow, you might try fixing that.
                    109: More generally, turning on optimization can significantly improve
                    110: `awk`'s speed, perhaps by 1/3 for highest levels.
                    111:
1.5     ! millert   112: ## A Note About Releases
        !           113:
        !           114: We don't do releases.
        !           115:
1.3       millert   116: ## A Note About Maintenance
                    117:
1.5     ! millert   118: NOTICE! Maintenance of this program is on a ''best effort''
1.3       millert   119: basis.  We try to get to issues and pull requests as quickly
                    120: as we can.  Unfortunately, however, keeping this program going
                    121: is not at the top of our priority list.
                    122:
1.1       millert   123: #### Last Updated
1.4       millert   124:
1.5     ! millert   125: Sat Jul 25 14:00:07 EDT 2021