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.
This commit is contained in:
parent
15b7f45ab2
commit
78d84ec74f
334
DOCS/MAKEFILE-STANDARDS.md
Normal file
334
DOCS/MAKEFILE-STANDARDS.md
Normal file
@ -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:=<path>:<owner>:<group>:<mode>
|
||||
```
|
||||
|
||||
### Required File Modes
|
||||
|
||||
#### 1. RPCD Scripts (755 - CRITICAL)
|
||||
|
||||
**Path Pattern:** `/usr/libexec/rpcd/luci.<module-name>`
|
||||
|
||||
**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/<module-name>/*.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/<module-name>`
|
||||
|
||||
**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 <contact@cybermind.fr>
|
||||
|
||||
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)
|
||||
Loading…
Reference in New Issue
Block a user