@profoundlogic/codermake 1.1.0 → 1.3.0

package/skills/codermake/references/compile-listings.md

@@ -0,0 +1,141 @@
+# Compile Listings Reference
+
+Guide to finding and interpreting IBM i compile listings produced by codermake builds.
+
+## Where to find logs
+
+Every build target produces a log file at:
+
+```
+tmp/logs/<target>.log
+```
+
+For example, building `mypgm.pgm` writes to `tmp/logs/mypgm.pgm.log`.
+
+## RPG listings (.rpgle)
+
+RPG compile listings from `CRTBNDRPG` or `CRTRPGMOD` follow a standard structure:
+
+1. **Header** -- compiler version, source file path, compile options
+2. **Source listing** -- numbered source lines (may include copy members)
+3. **Additional diagnostics** -- cross-reference tables, data structure layouts
+4. **Message summary** -- all diagnostic messages grouped by severity
+
+### Reading the message summary
+
+The message summary appears near the end of the listing. Each entry shows:
+
+```
+MSG ID    SEV  LINE  TEXT
+RNF7031   00   12    The name or indicator is not referenced.
+RNF7066   00   45    A semicolon is expected ...
+RNF5377   30   78    The type of expression does not match ...
+```
+
+**Severity levels:**
+
+| Severity | Meaning | Action |
+|---|---|---|
+| 00 | Informational | Safe to ignore |
+| 10 | Warning | Review but usually benign |
+| 20 | Error (recoverable) | Compiler attempted to continue; fix recommended |
+| 30 | Severe error | Compilation failed; must fix |
+| 40+ | Unrecoverable | Compilation failed; must fix |
+
+Search for severity 30+ messages to find the root cause of a build failure. The `LINE` column tells you which source line triggered the error.
+
+### Common RPG message IDs
+
+| ID prefix | Area |
+|---|---|
+| `RNF` | RPG compiler messages |
+| `RNS` | RPG compiler (structured) |
+| `SQL` | Embedded SQL messages (in SQLRPGLE) |
+
+## SQL RPG listings (.sqlrpgle)
+
+SQL RPG compilation is a two-phase process:
+
+1. **SQL precompile** (`CRTSQLRPGI`) -- translates embedded SQL into RPG call statements
+2. **RPG compile** -- compiles the resulting RPG source
+
+The log contains output from both phases. When debugging:
+
+- **SQL errors** appear in the first phase. Look for `SQL` message IDs.
+- **RPG errors** appear in the second phase. Look for `RNF`/`RNS` message IDs.
+- If the SQL precompile fails, the RPG compile does not run.
+
+### SQL precompile messages
+
+```
+SQL0104   30   Position 45  Token "SELEC" was not valid. Valid tokens: ...
+SQL0204   20   Table "MYLIB/NOTABLE" not found.
+```
+
+The position or line number tells you where in the embedded SQL the error occurred.
+
+## CL listings (.clle, .clp, .cl)
+
+CL compile errors appear as `CPD` or `CPF` messages:
+
+```
+CPD0727   30   The character value specified is not a valid name.
+CPF0001   40   Error found on CALL command.
+```
+
+For ILE CL (`CRTBNDCL`, `CRTCLMOD`), the listing structure is similar to RPG -- source listing followed by a message summary.
+
+For OPM CL (`CRTCLPGM`), the output is typically shorter and errors reference source sequence numbers.
+
+## DDS listings (.dspf, .pf, .lf, .prtf)
+
+DDS compilation errors from `CRTDSPF`, `CRTPF`, `CRTLF`, or `CRTPRTF` produce `CPD` messages:
+
+```
+CPD7302   30   Record format SCREEN1 not found in file referenced.
+CPD7344   30   Keyword REF not valid for this type of file.
+```
+
+DDS errors typically reference a specific record format and line within the source.
+
+## SQL DDL listings (.table.sql, .index.sql, .proc.sql)
+
+SQL DDL statements executed via `RUNSQLSTM` produce SQL messages:
+
+```
+SQL0104   30   Token "CREAT" was not valid.
+SQL0601   20   Table EMPLOYEE in MYLIB already exists.
+SQL7905   10   Module *N in *N not found.
+```
+
+- Severity 30+ means the statement failed.
+- Severity 20 warnings (like "already exists") may or may not be a problem depending on context.
+
+## Message files and binding directories (.msgf, .bnddir)
+
+These execute CL commands from a source file. Errors appear as `CPF` or `CPD` messages from the individual CL commands:
+
+```
+CPF2112   40   Object APPMSG type *MSGF already exists in library MYLIB.
+CPF2105   30   Object MYSRVPGM in MYLIB type *SRVPGM not found.
+```
+
+## Practical example
+
+A build of `mypgm.pgm` fails. Here is how to diagnose it:
+
+```bash
+# 1. Check the log
+cat tmp/logs/mypgm.pgm.log
+
+# 2. Search for high-severity messages
+grep -E 'RNF.{4}\s+[34]0|SQL.{4}\s+[34]0|CPD.{4}\s+[34]0|CPF.{4}\s+[34]0' tmp/logs/mypgm.pgm.log
+```
+
+Example output:
+
+```
+RNF5377   30   42    The type of expression does not match the type expected.
+```
+
+This tells you line 42 of the RPG source has a type mismatch. Open the source file, go to line 42, and fix the expression type.

package/skills/codermake/references/file-types.md

@@ -0,0 +1,243 @@
+# File Types Reference
+
+Complete reference for all source and object types supported by codermake. Each entry shows the Rules.mk syntax and the IBM i CL command used to compile it.
+
+## Programs (.pgm)
+
+### RPG program from .rpgle
+
+Compiles an ILE RPG source file into a bound program.
+
+```makefile
+mypgm.pgm: mypgm.rpgle
+```
+
+**CL command:** `CRTBNDRPG PGM(LIB/MYPGM) SRCSTMF('src/mypgm.rpgle')`
+
+### SQL RPG program from .sqlrpgle
+
+Compiles an RPG source file with embedded SQL into a bound program. Two-phase compilation: SQL precompile, then RPG compile.
+
+```makefile
+mypgm.pgm: mypgm.sqlrpgle
+```
+
+**CL command:** `CRTSQLRPGI OBJ(LIB/MYPGM) OBJTYPE(*PGM) SRCSTMF('src/mypgm.sqlrpgle')`
+
+### ILE CL program from .clle
+
+Compiles an ILE CL source file into a bound program.
+
+```makefile
+mypgm.pgm: mypgm.clle
+```
+
+**CL command:** `CRTBNDCL PGM(LIB/MYPGM) SRCSTMF('src/mypgm.clle')`
+
+### OPM CL program from .clp or .cl
+
+Compiles an OPM CL source file into a program. Uses source members (not stream files). OPM CL cannot be compiled to modules.
+
+```makefile
+mypgm.pgm: mypgm.clp
+```
+
+**CL command:** `CRTCLPGM PGM(LIB/MYPGM) SRCFILE(LIB/QCLSRC)`
+
+### SQL procedure from .proc.sql
+
+Runs a SQL DDL script that creates a stored procedure. The resulting object appears as a program.
+
+```makefile
+getcount.pgm: getcount.proc.sql
+```
+
+**CL command:** `RUNSQLSTM SRCSTMF('src/getcount.proc.sql') COMMIT(*NONE) DFTRDBCOL(LIB)`
+
+### Program from modules
+
+Links one or more compiled modules into a program. All prerequisites must be `.module` targets.
+
+```makefile
+mypgm.pgm: mod1.module mod2.module
+```
+
+**CL command:** `CRTPGM PGM(LIB/MYPGM) MODULE(LIB/MOD1 LIB/MOD2)`
+
+## Modules (.module)
+
+Modules are intermediate compile units that are linked into programs or service programs.
+
+### RPG module from .rpgle
+
+```makefile
+mymod.module: mymod.rpgle
+```
+
+**CL command:** `CRTRPGMOD MODULE(LIB/MYMOD) SRCSTMF('src/mymod.rpgle')`
+
+### SQL RPG module from .sqlrpgle
+
+```makefile
+mymod.module: mymod.sqlrpgle
+```
+
+**CL command:** `CRTSQLRPGI OBJ(LIB/MYMOD) OBJTYPE(*MODULE) SRCSTMF('src/mymod.sqlrpgle')`
+
+### ILE CL module from .clle
+
+```makefile
+mymod.module: mymod.clle
+```
+
+**CL command:** `CRTCLMOD MODULE(LIB/MYMOD) SRCSTMF('src/mymod.clle')`
+
+## Service programs (.srvpgm)
+
+A service program is created from one or more modules plus an export list (`.exports` file). The export list defines which procedures are visible to callers.
+
+```makefile
+mymod.module: mymod.rpgle
+mysrvpgm.srvpgm: mymod.module mysrvpgm.exports
+```
+
+**CL command:** `CRTSRVPGM SRVPGM(LIB/MYSRVPGM) MODULE(LIB/MYMOD) EXPORT(*SRCFILE) SRCSTMF('src/mysrvpgm.exports')`
+
+### .exports file format
+
+The exports file is a plain text file with the following structure:
+
+```
+STRPGMEXP PGMLVL(*CURRENT) SIGNATURE(*GEN)
+  EXPORT SYMBOL("procedureName")
+  EXPORT SYMBOL("anotherProc")
+ENDPGMEXP
+```
+
+List every procedure that callers should be able to invoke. Procedure names are case-sensitive and must match the RPG prototype names exactly.
+
+## Files (.file)
+
+The `.file` target extension covers several distinct IBM i object types, differentiated by the source extension.
+
+### Display file from .dspf
+
+Creates a display file from DDS source.
+
+```makefile
+myscreen.file: myscreen.dspf
+```
+
+**CL command:** `CRTDSPF FILE(LIB/MYSCREEN) SRCFILE(LIB/QDDSSRC)`
+
+### Rich Display File from .json
+
+Creates a display file from Profound UI Rich Display File JSON. The JSON is converted to DDS before compilation.
+
+```makefile
+myscreen.file: myscreen.json
+```
+
+**CL command:** `CRTDSPF FILE(LIB/MYSCREEN) SRCFILE(LIB/QDDSSRC) ENHDSP(*YES)`
+
+### Physical file from .pf
+
+Creates a physical file from DDS source.
+
+```makefile
+custdata.file: custdata.pf
+```
+
+**CL command:** `CRTPF FILE(LIB/CUSTDATA) SRCFILE(LIB/QDDSSRC)`
+
+### Logical file from .lf
+
+Creates a logical file (view/index over a physical file) from DDS source. Typically depends on the physical file it references.
+
+```makefile
+custview.file: custview.lf custdata.file
+```
+
+**CL command:** `CRTLF FILE(LIB/CUSTVIEW) SRCFILE(LIB/QDDSSRC)`
+
+### Printer file from .prtf
+
+Creates a printer file from DDS source.
+
+```makefile
+report.file: report.prtf
+```
+
+**CL command:** `CRTPRTF FILE(LIB/REPORT) SRCFILE(LIB/QDDSSRC)`
+
+### SQL table from .table.sql
+
+Creates a SQL table by running a DDL script.
+
+```makefile
+employee.file: employee.table.sql
+```
+
+**CL command:** `RUNSQLSTM SRCSTMF('src/employee.table.sql') COMMIT(*NONE) DFTRDBCOL(LIB)`
+
+### SQL index from .index.sql
+
+Creates a SQL index by running a DDL script. Typically depends on the table it indexes.
+
+```makefile
+empname.file: empname.index.sql employee.file
+```
+
+**CL command:** `RUNSQLSTM SRCSTMF('src/empname.index.sql') COMMIT(*NONE) DFTRDBCOL(LIB)`
+
+## Menus (.menu)
+
+A menu object requires both a display file and a message file.
+
+```makefile
+mymenu.menu: mymenu.file mymenu.msgf
+```
+
+**CL command:** `CRTMNU MENU(LIB/MYMENU) TYPE(*DSPF) DSPF(LIB/MYMENU) MSGF(LIB/MYMENU)`
+
+## Message files (.msgf)
+
+Message files use the dual-purpose pattern: the `.msgf` extension is both the source and the target. The source file contains CL commands that create and populate the message file.
+
+```makefile
+# Build the message file
+appmsg.msgf: appmsg.msgf
+
+# Use as a dependency (treated as a built object)
+mymenu.menu: mymenu.file appmsg.msgf
+```
+
+**Typical source content (src/appmsg.msgf):**
+
+```cl
+CRTMSGF MSGF($LIBRARY/$NAME)
+ADDMSGD MSGID(MSG0001) MSGF($LIBRARY/$NAME) MSG('First message') SECLVL('Detail text')
+```
+
+The `$LIBRARY` and `$NAME` variables are set automatically by codermake at build time.
+
+## Binding directories (.bnddir)
+
+Binding directories also use the dual-purpose pattern. The source file contains CL commands that create the binding directory and add entries to it.
+
+```makefile
+# Build the binding directory (order-only dep ensures srvpgm exists first)
+mybnddir.bnddir: mybnddir.bnddir | mysrvpgm.srvpgm
+
+# Use as order-only dependency
+mypgm.pgm: mypgm.rpgle mysrvpgm.srvpgm | mybnddir.bnddir
+```
+
+**Typical source content (src/mybnddir.bnddir):**
+
+```cl
+CRTBNDDIR BNDDIR($LIBRARY/$NAME)
+ADDBNDDIRE BNDDIR($LIBRARY/$NAME) OBJ(($LIBRARY/MYSRVPGM *SRVPGM))
+```
+
+Binding directories are almost always used as order-only prerequisites (`|`) because they must exist at compile time but should not trigger rebuilds when their content changes.