From 78d84ec74f9f76de4feb92f77e30f6ee59f15a48 Mon Sep 17 00:00:00 2001 From: CyberMind-FR Date: Sun, 28 Dec 2025 14:35:33 +0100 Subject: [PATCH] docs: Add comprehensive Makefile standards documentation - Complete guide for PKG_FILE_MODES configuration - Standard comment block template for all modules - File permission reference table (755 for RPCD, 644 for others) - Common errors and solutions - Validation and troubleshooting guides - Best practices for development Covers: - RPCD scripts (755 - CRITICAL for ubus calls) - Helper scripts (755 for executables) - Config files (644 - auto-set) - CSS/JS files (644 - auto-set by luci.mk) - Multi-line PKG_FILE_MODES syntax Reference for all SecuBox developers. --- DOCS/MAKEFILE-STANDARDS.md | 334 +++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 DOCS/MAKEFILE-STANDARDS.md diff --git a/DOCS/MAKEFILE-STANDARDS.md b/DOCS/MAKEFILE-STANDARDS.md new file mode 100644 index 0000000..70d0b49 --- /dev/null +++ b/DOCS/MAKEFILE-STANDARDS.md @@ -0,0 +1,334 @@ +# Makefile Standards for SecuBox LuCI Applications + +**Version:** 1.0.0 +**Last Updated:** 2025-12-28 +**Status:** Active Standard + +--- + +## Overview + +This document defines the standardized structure and conventions for all `luci-app-*` Makefile configurations in the SecuBox project. Following these standards ensures consistency, maintainability, and proper functionality across all modules. + +--- + +## File Permissions (PKG_FILE_MODES) + +### Purpose +The `PKG_FILE_MODES` variable explicitly sets file ownership and permissions for files installed by the package. This is **CRITICAL** for proper module functionality. + +### Standard Comment Block + +All Makefiles **MUST** include this comment block before `PKG_FILE_MODES`: + +```makefile +# File permissions (CRITICAL: RPCD scripts MUST be executable 755) +# Format: path:owner:group:mode +# - RPCD scripts: 755 (executable by root, required for ubus calls) +# - Helper scripts: 755 (if executable) +# - Config files: 644 (readable by all, writable by root) +# - CSS/JS files: 644 (set automatically by luci.mk) +``` + +### Format + +```makefile +PKG_FILE_MODES:=::: +``` + +### Required File Modes + +#### 1. RPCD Scripts (755 - CRITICAL) + +**Path Pattern:** `/usr/libexec/rpcd/luci.` + +**Mode:** `755` (rwxr-xr-x) + +**Rationale:** +- RPCD scripts MUST be executable by root +- Required for ubus RPC calls from the frontend +- Without 755, the backend will fail silently +- Validation: `./secubox-tools/validate-modules.sh` checks this + +**Example:** +```makefile +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755 +``` + +#### 2. Helper Scripts (755 - If Applicable) + +**Path Pattern:** `/usr/libexec//*.sh` + +**Mode:** `755` (rwxr-xr-x) + +**Rationale:** +- Shell scripts that need execution permissions +- Used for cron jobs, maintenance tasks, or utilities + +**Example:** +```makefile +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.secubox:root:root:755 \ + /usr/libexec/secubox/fix-permissions.sh:root:root:755 +``` + +#### 3. Configuration Files (644 - Default) + +**Path Pattern:** `/etc/config/` + +**Mode:** `644` (rw-r--r--) + +**Rationale:** +- UCI config files are world-readable +- Only root can write +- Set automatically by OpenWrt, no explicit PKG_FILE_MODES needed + +#### 4. CSS/JS Files (644 - Automatic) + +**Path Pattern:** `/www/luci-static/resources/**/*.{css,js}` + +**Mode:** `644` (rw-r--r--) + +**Rationale:** +- Web assets must be readable by all users +- Set automatically by `luci.mk` +- **DO NOT** add to PKG_FILE_MODES (redundant) + +--- + +## Multi-Line PKG_FILE_MODES + +When specifying multiple files, use backslash continuation: + +```makefile +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.secubox:root:root:755 \ + /usr/libexec/secubox/fix-permissions.sh:root:root:755 \ + /usr/libexec/secubox/health-check.sh:root:root:755 +``` + +**Rules:** +- Backslash `\` at end of line for continuation +- Indent continuation lines with TAB +- Last line has NO backslash +- One space between backslash and newline + +--- + +## Common Errors and Solutions + +### Error 1: RPCD Backend Not Responding + +**Symptom:** +``` +RPC call to luci.module-name/method failed with error -32000: Object not found +``` + +**Cause:** RPCD script not executable (missing 755 permissions) + +**Solution:** +```makefile +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.module-name:root:root:755 +``` + +**Validation:** +```bash +./secubox-tools/validate-modules.sh +# OR +./secubox-tools/fix-permissions.sh --local +``` + +--- + +### Error 2: CSS/JS Files Added to PKG_FILE_MODES + +**Wrong:** +```makefile +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755 \ + /www/luci-static/resources/system-hub/api.js:root:root:644 +``` + +**Right:** +```makefile +# CSS/JS files are automatically set by luci.mk +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755 +``` + +**Rationale:** The LuCI build system (`luci.mk`) automatically sets correct permissions for all files in `/www/`. Adding them to `PKG_FILE_MODES` is redundant and can cause conflicts. + +--- + +### Error 3: Missing Comment Block + +**Wrong:** +```makefile +LUCI_PKGARCH:=all + +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755 +``` + +**Right:** +```makefile +LUCI_PKGARCH:=all + +# File permissions (CRITICAL: RPCD scripts MUST be executable 755) +# Format: path:owner:group:mode +# - RPCD scripts: 755 (executable by root, required for ubus calls) +# - Helper scripts: 755 (if executable) +# - Config files: 644 (readable by all, writable by root) +# - CSS/JS files: 644 (set automatically by luci.mk) +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.system-hub:root:root:755 +``` + +--- + +## Validation Tools + +### Automated Validation + +**Before Commit:** +```bash +./secubox-tools/validate-modules.sh +``` + +Checks: +1. RPCD script names match ubus objects +2. Menu paths match view file locations +3. View files have menu entries +4. **RPCD scripts are executable (755)** +5. JSON syntax validation +6. ubus object naming convention +7. **htdocs file permissions (644 for CSS/JS)** + +**Auto-Fix Permissions:** +```bash +# Fix local files before build +./secubox-tools/fix-permissions.sh --local + +# Fix deployed files on router +./secubox-tools/fix-permissions.sh --remote +``` + +--- + +## Complete Makefile Template + +```makefile +include $(TOPDIR)/rules.mk + +PKG_NAME:=luci-app-module-name +PKG_VERSION:=0.3.5 +PKG_RELEASE:=1 +PKG_LICENSE:=Apache-2.0 +PKG_MAINTAINER:=CyberMind + +LUCI_TITLE:=Module Title - Short Description +LUCI_DESCRIPTION:=Comprehensive description of module functionality +LUCI_DEPENDS:=+luci-base +rpcd +optional-dependency +LUCI_PKGARCH:=all + +# File permissions (CRITICAL: RPCD scripts MUST be executable 755) +# Format: path:owner:group:mode +# - RPCD scripts: 755 (executable by root, required for ubus calls) +# - Helper scripts: 755 (if executable) +# - Config files: 644 (readable by all, writable by root) +# - CSS/JS files: 644 (set automatically by luci.mk) +PKG_FILE_MODES:=/usr/libexec/rpcd/luci.module-name:root:root:755 + +include $(TOPDIR)/feeds/luci/luci.mk + +# Optional: Config files to preserve on upgrade +define Package/$(PKG_NAME)/conffiles +/etc/config/module-name +endef + +# call BuildPackage - OpenWrt buildroot signature +``` + +--- + +## File Mode Reference Table + +| File Type | Path Pattern | Owner:Group | Mode | Reason | +|-----------|-------------|-------------|------|--------| +| RPCD script | `/usr/libexec/rpcd/luci.*` | root:root | 755 | **CRITICAL** - Must be executable for ubus calls | +| Helper script | `/usr/libexec/*/*.sh` | root:root | 755 | Executable scripts (cron, maintenance) | +| UCI config | `/etc/config/*` | root:root | 644 | World-readable, root-writable (auto-set) | +| CSS/JS files | `/www/luci-static/**/*.{css,js}` | root:root | 644 | Web assets (auto-set by luci.mk) | +| Menu JSON | `/usr/share/luci/menu.d/*.json` | root:root | 644 | LuCI menu definitions (auto-set) | +| ACL JSON | `/usr/share/rpcd/acl.d/*.json` | root:root | 644 | Access control lists (auto-set) | + +--- + +## Best Practices + +### 1. **Always Validate Before Commit** +```bash +./secubox-tools/validate-modules.sh +``` + +### 2. **Use Standard Comment Block** +Copy from existing Makefile or this document. + +### 3. **Only Specify Executable Files** +Don't add CSS/JS/JSON files to PKG_FILE_MODES. + +### 4. **Test on Real Hardware** +Deploy to test router and verify: +```bash +ls -la /usr/libexec/rpcd/luci.module-name # Should be -rwxr-xr-x +ubus list | grep module-name # Should appear +ubus call luci.module-name status # Should respond +``` + +### 5. **Document Custom Permissions** +If adding non-standard file modes, add inline comments explaining why. + +--- + +## Troubleshooting + +### Permission Denied Errors + +**Check permissions on router:** +```bash +ssh root@router "ls -la /usr/libexec/rpcd/luci.*" +``` + +**Fix remotely:** +```bash +./secubox-tools/fix-permissions.sh --remote +``` + +### Files Not Installed + +**Check package contents:** +```bash +tar -tzf luci-app-module-name_*.ipk | grep rpcd +# OR (for .apk format) +tar -tzf luci-app-module-name_*.apk | grep rpcd +``` + +**Verify Makefile paths:** +Ensure `PKG_FILE_MODES` paths match actual file locations in the package. + +--- + +## References + +- [OpenWrt Makefile Documentation](https://openwrt.org/docs/guide-developer/packages) +- [LuCI Build System](https://github.com/openwrt/luci/blob/master/luci.mk) +- [DEVELOPMENT-GUIDELINES.md](./DEVELOPMENT-GUIDELINES.md) +- [QUICK-START.md](./QUICK-START.md) + +--- + +## Changelog + +### v1.0.0 (2025-12-28) +- Initial standardization across all 15 SecuBox modules +- Defined standard comment block format +- Documented file mode requirements +- Added validation and troubleshooting sections + +--- + +**Next Review:** 2026-01-28 (or when adding new modules)