Skip to content

Latest commit

 

History

History
114 lines (97 loc) · 5.24 KB

internals.md

File metadata and controls

114 lines (97 loc) · 5.24 KB

TECO-64 Internals Notes

Overview

This document is a work in progress. It provides a description of the design of TECO-64 for the benefit of those who maintain or enhance it, as well as those who are curious about how it is structured.

History

TECO-64 development began in October 2019 a on Linux/Ubuntu system, using gcc and other GNU tools. It has been successfully executed on Linux, Windows 10, and MacOS, although testing on the latter two is currently out of date. It was also successfully compiled on VMS, but was not able to be executed in that environment owing to the absence of additional run-time library support.

Development

The general guidelines used during development were:

  • Familiarity – Use names that are either familiar to the reader (e.g., with a Linux-like directory structure), or which are otherwise descriptive of their purpose (e.g., er_cmd.c for a file which processes the ER command).
  • Consistency – Use the same conventions in one place that are used in another (e.g., all functions which process specific commands have names of the form exec_*()).
  • Readability – Use names that can be pronounced (as opposed to an alphabet soup of acronyms), and as much as possible, use names that include verbs (e.g., reset_term() or clear_win()).
  • Simplicity – Avoid long functions. Also avoid large files containing numerous unrelated functions, and don’t duplicate code.
  • Modularity – Hide details of functions and modules as much as possible. This has made it possible to have more than one method for handling data in the edit buffer, and more than one method for handling paging.

Testing & Debugging

  • assert() statements were used to verify run-time assumptions, including the validity of function parameters.
  • PC-Lint was used to verify the correctness of code and detect possible bugs.
  • Valgrind was used to detect memory leaks, as was some added debug code.
  • strace was used to profile system calls.
  • gprof was used to profile function and library calls.
  • gdb was used for debugging.

Documentation

  • Doxygen comments were used in source code to provide in-line documentation.
  • XML and XSL files were used to create documentation as well as code defining TECO command-line options.
  • Markdown files were created for the README file, system-dependent setup notes, and the TECO reference manual.

Directory Names

  • ./ - Contains the makefile used to build TECO, and the README.md file.
  • ./bin - Contains the TECO-64 executable.
  • ./doc - Contains Markdown documentation files.
  • ./etc - Contains files used to build and test TECO.
    • ./etc/build - Contains supplemental files used by make.
    • ./etc/pattern - Contains files that are used in conjunction with XML and XSL files to generate other files used to compile code or create documentation.
    • ./etc/xml - Contains XML and XSL files that defines the run-time errors, the command-line options, and TECO's commands.
  • ./html - Contains documentation files generated by Doxygen.
  • ./include - Contains .h header files used for building TECO, as well as several files that will be generated if needed during the build process.
  • ./lib - Contains examples of TECO macro files.
  • ./obj - Contains generated object files created during the build process.
  • ./src - Contains the .c source files used to build TECO, and a configuration file used by PC-Lint.
  • ./test - Contains test scripts and other files used to test TECO commands and features.

File Names

  • cmd_*.c - Files that perform general processing of TECO commands.
  • *_cmd.c - Files that perform a specific TECO command (e.g., er_cmd.c contains code for processing ER commands), or perform multiple related TECO commands (e.g., yank_cmd.c contains code for processing commands that yank data into memory).
  • *_buf.c - Files that implement an interface for command, edit, or terminal buffers.
    • cmd_buf.c - Implements a command buffer interface.
    • gap_buf.c – Implements an edit buffer interface using a gap buffer method.
    • term_buf.c - Implements a terminal buffer interface.
  • page_*.c - Files that provide an interface for paging forward (and possibly backward) through a file. Only one of the following is used in any specific build:
    • page_file.c – Writes pages to output file, uses a temporary file to allow for backwards paging (TBD).
    • page_std.c – Writes pages to output file; no backwards paging implemented (classic TECO paging method).
    • page_vm.c – Writes pages to output file only when file is closed; virtual memory is used to store pages, which allows for backwards paging.
  • term_*.c - Files that process terminal input and output.
  • *_sys.c - Files that provide interfaces to system-dependent features. Code in all other files should be system-independent, but this is subject to change during further testing.

Function Names

  • *_cbuf() - Functions that implement a command buffer interface.
  • cmd_*() - Functions that provide general processing for TECO commands.
  • *_dpy() - Functions that implement a display window interface.
  • *_edit() - Functions that implement a edit buffer interface.
  • exec_*() - Functions that execute specific TECO commands.
  • *_tbuf() - Functions that implement a terminal buffer interface.