Skip to content

docs: style guide in HACKING, new AGENTS.md #242

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
GitMensch wants to merge 1 commit into
base: gcos4gnucobol-3.x
Choose a base branch
from
Open

docs: style guide in HACKING, new AGENTS.md #242

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 251 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,251 @@
# GnuCOBOL Development Agent Guide

This guide provides essential information for AI agents working on the GnuCOBOL project, covering project structure, coding conventions, testing practices, and development workflows.

## Project Structure

### Core Components
- **`cobc/`** - COBOL compiler source code
- Functions prefixed with `cobc_` (e.g., `cobc_print_usage`)
- Main compiler logic, parsing, code generation
- **`libcob/`** - Runtime library source code
- Functions prefixed with `cob_` (e.g., `cob_init`, `cob_decimal_pow`)
- Intrinsic functions, I/O operations, runtime support
- **`bin/`** - Runtime executables (`cobcrun`)
- **`tests/`** - Test suite using GNU Autotest framework
- **`config/`** - Compiler configuration files
- **`copy/`** - Standard COBOL copybooks

**Important**: All generated files (parser, scanner, build system, test scripts) are generated by `make`, not by invoking bison/flex/autotools directly. The build system handles all code generation.

### Build System
- **GNU Autotools** (autoconf, automake, libtool)
- **`configure.ac`** - Main configuration script
- **`Makefile.am`** - Build definitions
- **`pre-inst-env`** - Script for testing uninstalled binaries

## Testing Framework

### Test Organization
Tests are located in `tests/testsuite.src/` and organized by category:

- **`used_binaries.at`** - Tests for cobc/cobcrun binaries and command-line options
- **`configuration.at`** - Configuration and environment tests
- **`syn_*.at`** - Syntax validation tests (parsing, compilation)
- **`run_*.at`** - Runtime execution tests
- `run_functions.at` - Intrinsic function tests
- `run_fundamental.at` - Basic language features
- `run_misc.at` - Miscellaneous runtime tests

### Test Structure
Tests use GNU Autotest framework with these macros:
```m4
AT_SETUP([Test Name])
AT_KEYWORDS([category keywords])

AT_DATA([prog.cob], [
IDENTIFICATION DIVISION.
PROGRAM-ID. prog.
# COBOL code here
])

AT_CHECK([$COMPILE prog.cob], [0], [], [])
AT_CHECK([$COBCRUN_DIRECT ./prog], [0], [expected output], [])

AT_CLEANUP
```

### Environment Variables (from atlocal)
- **`$COBC`** - Path to cobc compiler, normally used only in used_binaries.at
- **`$COMPILE`** - Shorthand for compilation command
- **`$COBCRUN_DIRECT`** - Direct execution of programs compiled
- **`$COMPILE_MODULE`** - Shorthand for compilation as a module
- **`$COBCRUN`** - Path to cobcrun module loader
- **`$GREP`**, **`$SED`**, **`$DIFF`** - Configured utilities

### Testing Best Practices
1. **Always test through binaries** - Use `$COMPILE` and `$COBCRUN_DIRECT`, never test internal functions directly
2. **Add to existing test groups** - Place tests in appropriate `testsuite.src/*.at` files
3. **Follow existing patterns** - Match structure and style of surrounding tests
4. **Use meaningful test names** - Describe the specific functionality being tested
5. **Test edge cases** - Focus on boundary conditions and error paths

### Local Testing
For quick testing during development:
```bash
# Build with coverage
./configure --enable-code-coverage --enable-cobc-internal-checks --enable-debug
make

# Test individual programs
./pre-inst-env cobc/cobc -x test.cob
./pre-inst-env ./test

# Run specific test groups (use -k to filter tests)
make check TESTSUITEFLAGS="-k 'FUNCTION CHAR'"
make check TESTSUITEFLAGS="-k 'syntax'"
```

## Code Coverage Analysis

### Setup
```bash
# Install coverage tools
sudo apt-get install lcov

# Configure with coverage
./configure --enable-code-coverage --with-db --with-xml2 --with-curses=ncursesw

# Build and run tests
make
make check

# Generate coverage reports
make code-coverage-capture
```

### Coverage Workflow (from GitHub Actions)
1. Build with `--enable-code-coverage`
2. Run test suite: `make check TESTSUITEFLAGS="--jobs=$(($(nproc)+1))"`
3. Capture coverage: `make code-coverage-capture CODE_COVERAGE_DIRECTORY="$(realpath .)/_build"`
4. Generate HTML reports with lcov/genhtml
5. Use `-k` flag to run specific tests: `TESTSUITEFLAGS="-k 'FUNCTION'"`

### Coverage-Driven Development
- Use `gcov` to identify untested code paths
- Focus on functions with 0% coverage for new tests
- Prioritize edge cases and boundary conditions
- Verify tests improve coverage metrics

## Coding Style and Conventions

For complete coding style guidelines, see **`HACKING.md`**.

### Critical Points for Agents
- **C89/C90 compliance** - Data definitions at start of blocks, conditional compilation for newer features
- **Naming**: `cob_` prefix for libcob, `cobc_` for compiler, `COB_` for constants
- **Testing**: Always test through binaries (`$COBC`, `$COBCRUN_DIRECT`), never internal functions
- **ChangeLog**: Don't document individual test additions in `tests/ChangeLog` (only structural changes)


### Conditional Compilation Pattern
```c
#if defined (HAVE_CLOCK_GETTIME)
clock_gettime (CLOCK_REALTIME, &time_spec);
#elif defined (HAVE_SYS_TIME_H) && defined (HAVE_GETTIMEOFDAY)
gettimeofday (&tmv, NULL);
#else
curtime = time (NULL);
#endif
```

## ChangeLog Format

### Standard ChangeLog Format
All directories follow this format (date in ISO format, tab-indented entries):
```
YYYY-MM-DD Author Name <email@domain.com>

* file.c (function_name): description of change
* file.h: description of header changes
* configure.ac, Makefile.am: configuration changes

longer description if needed, indented with spaces

* another_file.c: another change
```

### Directory-Specific ChangeLogs
Each major directory maintains its own ChangeLog:

- **`/ChangeLog`** - Build system, configuration, top-level changes
- **`cobc/ChangeLog`** - Compiler changes (parsing, code generation, options)
- **`libcob/ChangeLog`** - Runtime library changes (intrinsics, I/O, core functions)
- **`tests/ChangeLog`** - **SPECIAL CASE** (see below)

### Tests ChangeLog Exception
**Important**: `tests/ChangeLog` only documents structural/infrastructure changes, **NOT** individual test additions.

**Document in tests/ChangeLog:**
- New test files (`testsuite.src/new_category.at`)
- Test infrastructure changes (`atlocal.in`, `run_prog_manual.sh.in`)
- Test framework modifications
- Environment variable changes
- Test runner improvements

**Do NOT document in tests/ChangeLog:**
- Adding individual test cases to existing files
- Modifying existing test cases
- Adding new `AT_SETUP` blocks
- Test case bug fixes

### ChangeLog Examples

**Main ChangeLog:**
```
2025-07-28 Simon Sobisch <simonsobisch@gnu.org>

* configure.ac: check timezone and designated initializers with -Werror
* m4/ax_code_coverage.m4, m4/ax_check_define.m4:
updated from autoconf-archive
```

**cobc/ChangeLog:**
```
2025-07-28 David Declerck <david.declerck@ocamlpro.com>

* codegen.c (output_module_init_function): replace "module" by
"module__" to avoid name clashes with COBOL programs named "module"
```

**tests/ChangeLog:**
```
2025-05-22 David Declerck <david.declerck@ocamlpro.com>

* atlocal.in, atlocal_win: set TZ=UTC globally
to help get a reproducible output
```

## Build Dependencies

For detailed dependency information including specific versions and platform notes, see:
- **`DEPENDENCIES`** - Complete list of required and optional dependencies
- **`HACKING`** - Development setup and build instructions

### Key Points
- **BOTH runtime AND development components** required for all libraries
- **GNU MP (libgmp)** OR **MPIR** required for decimal arithmetic
- **Always prefer distribution packages** over manual compilation
- Optional libraries enable specific features (curses, Berkeley DB, XML, JSON)
- See DEPENDENCIES for version requirements and platform-specific notes

## Common Development Tasks

### Adding a New Test
1. Identify appropriate test file in `tests/testsuite.src/`
2. Add test following existing patterns
3. Test manually with `./pre-inst-env`
4. **Do not** document in `tests/ChangeLog`

### Adding a New Function
1. Implement in appropriate source file (`cobc/` or `libcob/`)
2. Add declaration to header file only when called from other sources;
Use forward declarations for local functions if necessary, otherwise order the static functions as needed
3. Add tests covering main execution paths and edge cases
4. Document in main `ChangeLog`

### Debugging Build Issues
1. Check `config.log` for configuration problems
2. Ensure all dependencies are installed
3. Use `./pre-inst-env` for testing uninstalled binaries
4. Check compiler warnings for C89 compliance

## Key Files to Understand

- **`configure.ac`** - Build configuration and feature detection
- **`libcob/common.h`** - Core type definitions and macros
- **`cobc/cobc.h`** - Compiler internal definitions
- **`tests/atlocal.in`** - Test environment setup
- **`pre-inst-env`** - Development testing script

This guide should provide sufficient context for effective development work on the GnuCOBOL project while following established conventions and practices.
Loading
Loading