73 lines
5.1 KiB
Markdown
73 lines
5.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `src/` holds the shell implementation, with submodules for `builtins/`, `executor/`, `parser/`, and `variables/`.
|
|
- `src/builtins/` currently includes: `cd`, `echo`, `env`, `exit`, `export`, `pwd`, `unset`.
|
|
- `src/executor/` includes pipeline/process orchestration plus file redirections in `redirections.c`.
|
|
- `include/` contains public headers used across modules.
|
|
- `lib/` is populated at build time with third-party 42 libraries (libft, get_next_line, ft_printf, ft_args).
|
|
- `docs/` stores project references and manual test notes (see `docs/tests.md`).
|
|
- `build/` is the object output directory generated by `make`.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `make` or `make all`: build `minishell` (auto-clones required libs into `lib/`).
|
|
- `make clean`: remove objects in `build/`.
|
|
- `make fclean`: remove objects and the `minishell` binary (also cleans libs).
|
|
- `make re`: full rebuild.
|
|
- `./minishell`: run locally after a build.
|
|
- `make DEBUG=lldb` or `make DEBUG=valgrind` or `make DEBUG=address`: rebuild with debug/ASan-friendly flags.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- The codebase follows 42 **Norminette v4** rules. Run `norminette *.c *.h` (or on specific files) before submitting changes.
|
|
- Keep file names lowercase with underscores (e.g., `src/builtins/echo/echo.c`).
|
|
- Keep headers in `include/` and expose only what modules need.
|
|
- Before adding or changing code, check `allowed.txt` to know which functions are permitted.
|
|
- Any function not listed in `allowed.txt` is not allowed in this project.
|
|
|
|
## Parser & Lexer Functionality (Current `src/parser`)
|
|
- Runtime entrypoint is `parse(line, minishell)` from `src/minishell.c` (`readline -> parse -> execute`).
|
|
- `parse` calls `lex(line)` and then converts token lists to `t_command` nodes with `parse_tokens`.
|
|
- `command_new` builds one command from tokens up to `TOKEN_PIPE`.
|
|
- `words_add` stores consecutive `TOKEN_WORD` tokens in `command->argv` and increments `argc`.
|
|
- `expand_envs` is currently a TODO (no `$VAR` expansion is applied in parser stage).
|
|
- Redirection tokens are converted into `t_redirection` and stored in `t_command.redirections`; heredocs are stored in `t_command.heredocs`.
|
|
- Path resolution is handled in executor (`executor_resolve_command_path`) before `execve`.
|
|
- `src/parser/lexer.c` provides a separate lexer (`lex`) that tokenizes into `TOKEN_WORD`, `TOKEN_PIPE`, `TOKEN_REDIRECT_IN`, `TOKEN_REDIRECT_OUT`, `TOKEN_APPEND`, and `TOKEN_HEREDOC`.
|
|
- The lexer tracks single/double quote context so metacharacters inside quotes remain part of words.
|
|
- Meta runs are read as contiguous chunks in `read_token` (for example, repeated `|`/`<`/`>` are captured as one token value).
|
|
- Current parser flow consumes lexer output directly.
|
|
|
|
## Executor Redirections (Current `src/executor`)
|
|
- File redirections are applied in `src/executor/redirections.c` via `open` + `dup2` before command execution.
|
|
- Supported file redirections: input `<`, output truncate `>`, output append `>>`.
|
|
- Redirections are applied for both forked commands (child path) and single builtins executed in parent.
|
|
- Parent-builtin redirections save/restore `STDIN_FILENO` and `STDOUT_FILENO` after builtin execution.
|
|
|
|
## Parser & Lexer Known Gaps
|
|
- Heredoc tokens are parsed and stored, but runtime heredoc execution/input feeding is still pending in executor.
|
|
- No explicit unmatched-quote syntax error handling is implemented in parser/lexer path.
|
|
|
|
## Testing Guidelines
|
|
- There is no automated test runner. Use manual checks in `docs/tests.md` and basic shell behavior checks (pipes, redirects, builtins).
|
|
- A local builtin edge-case script exists at `tests/builtins_edge_cases.sh` (expects a compiled `./minishell`).
|
|
- When debugging memory issues, run under valgrind and use the suppression file in `valgrind/readline.supp`.
|
|
|
|
## Builtins Status
|
|
- `cd`: handles `HOME` fallback, `cd -` via `OLDPWD`, updates `PWD`/`OLDPWD`, and returns failure on invalid usage (`too many arguments`, missing `HOME`/`OLDPWD`).
|
|
- `echo`: supports repeated `-n` flags (`-n`, `-nnn`) and prints remaining args preserving spaces between tokens.
|
|
- `env`: prints current environment as `KEY=VALUE`; returns failure when called with extra arguments.
|
|
- `exit`: validates numeric argument (with overflow checks), returns `1` on `too many arguments` without exiting, and exits with `2` on non-numeric argument.
|
|
- `export`: supports `NAME=VALUE` and `NAME` (stored as empty value), validates identifiers, and returns failure when any identifier is invalid.
|
|
- `pwd`: prints working directory using dynamic `getcwd` and returns failure if `getcwd` fails.
|
|
- `unset`: validates identifiers and removes matching variables from the environment map.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Commit messages in this repo use a simple `type: summary` format (examples: `update: ...`, `fix: ...`). Keep summaries short and specific.
|
|
- For PRs, include:
|
|
1. What changed and why.
|
|
2. How to test (commands or manual steps).
|
|
3. Notes on any parser/executor/builtin behavior changes.
|
|
|
|
## Configuration Tips
|
|
- The project depends on `readline`; ensure your system has `libreadline-dev` or equivalent before building.
|