diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3304056 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# AGENTS.md + +## Project + +**desktoplib** — Cross-platform C++20 library for terminal UIs, process management, and serial (USB) communication. Namespace: `ckitty`. + +## Build + +```bash +make -f makelib.mak # Build static library (out/libdesktoplib.a) +make # Build test executable (out/out.exe) +make -f makelib.mak remake # Clean and rebuild library +``` + +Compiler: `g++` with `-std=c++20` (developed with MSYS2/UCRT64 on Windows). Test build defines `DESKTOPLIB_TEST` and links `src/desktoplib/main.cpp`. + +## Conventions + +- Headers use `#pragma once` +- Source lives under `src/desktoplib//` +- OS abstraction: `os/common.hpp` declares interface; `os/unix.cpp` and `os/windows.cpp` implement platform-specific behavior +- Terminal methods chain via `Terminal&` return +- ANSI escape sequences are encapsulated in `color`, `backg`, `style`, `pos`, `move`, `key` +- `Terminal` has friend access to `color`/`backg`/`style` private constructors +- UI elements inherit from `ckitty::terminal::UI` and implement `render(Terminal&)` + +## Module Layout + +``` +src/desktoplib/ +├── main.cpp # Test harness (compiled when DESKTOPLIB_TEST is defined) +├── os/ +│ ├── common.hpp # Cross-platform terminal OS interface +│ ├── unix.cpp # POSIX implementations +│ └── windows.cpp # Windows implementations +├── terminal/ +│ ├── Terminal.hpp/cpp # Core terminal output/input engine +│ ├── UI.hpp # Abstract UI base class +│ └── ui/ +│ ├── Box.hpp/cpp # Bordered box widget +│ ├── InnerScroll.hpp/cpp # Scrollbar widget +│ ├── MenuMap.hpp # 2D navigation grid +│ └── Content.hpp # Virtual content renderer base +└── proc/ + ├── Process.hpp # Stub: planned process abstraction + └── Process.cpp +``` + +## Current State + +- **Terminal**: functional (ANSI colors, RGB/HSL, cursor positioning, input, UI widgets) +- **Process**: stub only — `class Process {};` +- **Serial**: not yet started + +## Notes + +- Do not add comments unless explicitly requested +- Follow existing naming: module directories are lowercase, classes are PascalCase, methods/variables are camelCase +- When extending OS abstraction, update `common.hpp` first, then both `unix.cpp` and `windows.cpp` diff --git a/README.md b/README.md index 8cb907d..c823b2f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,85 @@ # desktoplib -A library that helps when building desktop apps by adding support for Terminals, Serial interfaces, and other general desktop-only things. +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -Designed as a standalone library, so its scope is intentionally limited. -ckittylib: Not required. +A lightweight, cross-platform C++20 library for building desktop applications that need uniform access to terminal UIs, OS processes, and serial (USB) interfaces. + +Designed as a standalone static library with an intentionally limited scope. No heavy dependencies — just standard C++20 and platform-specific OS calls. + +## Features + +- **Terminal UI** — ANSI escape-sequenced output with RGB/HSL colors, cursor positioning, alternative buffers, and input handling +- **UI Widgets** — Built-in `Box`, `InnerScroll`, `MenuMap`, and `Content` for composing terminal layouts +- **Process Management** — Planned uniform process spawn/stream abstraction (stub in place) +- **Serial Communication** — Planned cross-platform USB/serial port interface +- **OS Abstraction Layer** — Shared terminal/input/OS calls behind `common.hpp`, with POSIX and Windows implementations + +## Requirements + +- C++20 compatible compiler (`g++` recommended) +- Make (GNU Make) +- POSIX or Windows environment + +## Building + +```bash +# Build the static library +make -f makelib.mak + +# Build and run the test executable +make +./out/out.exe +``` + +Produces `out/libdesktoplib.a` for linking into your own projects. + +## Quick Start + +```cpp +#include + +int main() { + using namespace ckitty::terminal; + + Terminal term; + term.altbuff(true) + .cursor(false) + .cls() + .fill(color::B_BLACK); + + term << pos{ 1, 1 } << backg::BLUE << color::WHITE << style::BOLD; + term.center(40, " Hello, desktoplib "); + term << style::RESET; + + term.flush(); + term.wait(); // Block until a key is pressed + + term.altbuff(false).cursor(true).cls(); + return 0; +} +``` + +## Architecture + +``` +src/desktoplib/ +├── os/ # Platform abstraction (POSIX / Windows) +├── terminal/ # Terminal engine, ANSI codes, input +│ └── ui/ # Widgets: Box, InnerScroll, MenuMap, Content +└── proc/ # Process management (stub) +``` + +All modules live in the `ckitty` namespace. The terminal layer uses ANSI escape sequences wrapped in typed structs (`color`, `backg`, `style`, `pos`, `move`) and supports method chaining on `Terminal`. + +## Roadmap + +| Module | Status | Target | +|--------|--------|--------| +| Terminal UI | Stable | — | +| OS Abstraction | Stable (POSIX + Windows) | — | +| Process | Stub | Spawn, stdin/stdout/stderr streams, exit code | +| Serial / USB | Not started | Cross-platform port enumeration + read/write | + +## License + +MIT — see [LICENSE](LICENSE). diff --git a/src/desktoplib/proc/Process.hpp b/src/desktoplib/proc/Process.hpp index 055092d..a0fa67d 100644 --- a/src/desktoplib/proc/Process.hpp +++ b/src/desktoplib/proc/Process.hpp @@ -1,11 +1,66 @@ #pragma once +#include +#include +#include +#include +#include + namespace ckitty { /** * Represents a process, which is executed by an OS. * It exposes streams to the input and output of the process. */ - class Process {}; + class Process { + private: + + public: + + Process(); + + ~Process(); + + public: + + /** + * Sets the program string. + */ + void setExec(std::string_view view); + + /** + * Sets the parameters, with a map map. + * They can also be passed as a raw string in the setExec method. + */ + void setParams(); + + /** + * Starts executing the program. + */ + void run(); + + bool isRunning(); + + /** + * Returns the stop code. + * Returns 0 if the code is still running. + */ + int stopCode(); + + void addInput(std::string_view view); + + /** + * Receives all the output so far. + */ + std::string_view getOutput(); + + /** + * Receives the output fresh from the pipe. + */ + std::string_view nextOutput(); + + // same pipe for error... + + }; } \ No newline at end of file