Developer FAQ
Frequently asked questions about developing for ProteanOS.
Frequently Asked Questions
How do I start developing for ProteanOS?
Install ProKit and work through the ProKit documentation first. The fastest path is to take an existing package from the git repositories, build it with ProKit, then modify it. Reading a working package before writing one from scratch saves a lot of time - the control file and rules file structure becomes obvious immediately when you can see a concrete example alongside the SPF 2.0 specification.
What development tools do I need?
ProKit handles the cross-compilation toolchain setup. You need a Linux development host (or a Linux VM), GCC, make, and standard POSIX utilities. ProKit installs the target-specific sysroot and sets up the environment variables that your build rules run inside. The install guide covers the initial setup.
What is the relationship between ProKit and opkg?
ProKit is the build and packaging tool used by developers - it compiles source packages and produces OPK binary packages. opkg is the package manager that runs on the target device and installs those binary packages. You use ProKit on your development host; opkg runs on ProteanOS itself.
Where is the source code hosted?
All ProteanOS repositories are available at git.proteanos.com. The ProKit source, package repositories, and infrastructure tooling are all there. You can browse them through the web interface or clone with git directly.
Packaging Questions
Frequently Asked Questions
What package format does ProteanOS use?
Binary packages use the OPK format (an extension of the IPK format used by OpenWrt and OpenEmbedded). Source packages follow Source Package Format 2.0, which defines the control file, build rules file, changelog, copyright, and optional patch series. The SPF 2.0 specification documents all required and optional fields.
What is required in the control file?
At minimum, the source stanza needs Source, Format, Maintainer, and Build-Depends. Each binary package stanza needs Package, Architecture, and Description. Dependencies use the same syntax as Debian - comma-separated package names with optional version constraints. The SPF 2.0 spec has the full field reference.
How are build-time and runtime dependencies handled?
Build-time dependencies go in Build-Depends in the source stanza. Runtime dependencies go in Depends in the binary package stanza. ProKit resolves build dependencies before starting the build; opkg resolves runtime dependencies on the target at install time. You can use substitution variables like ${shlibs:Depends} to let the tooling auto-detect shared library dependencies.
How do I package software that needs patching?
Put patches in the patches/ directory and list them in patches/series in the order they should be applied. ProKit applies them before the configure step. Name patches descriptively - something like 01-fix-cross-compilation.patch - and keep each patch focused on one change so they are easier to forward-port when the upstream version changes.
Build System
Frequently Asked Questions
How does cross-compilation work in ProKit?
Sourcing the ProKit environment script sets CROSS_COMPILE, CC, CXX, SYSROOT, PKG_CONFIG_PATH, and the other variables your build rules need. The rules file invokes the compiler through those variables. For autoconf-based packages, passing --host to configure is usually sufficient; cmake packages need CMAKE_TOOLCHAIN_FILE or explicit -DCMAKE_SYSTEM_PROCESSOR settings.
My package builds natively but fails cross-compilation. Where do I start?
The most common causes are hardcoded paths (using /usr instead of $(SYSROOT)/usr), host detection going wrong in configure scripts, and build tools that execute compiled binaries during the build (which fails when the target arch differs from the host). Run prokit build --verbose and look for the first error. Check whether configure detected the correct host triplet with --host set properly.
How do I speed up builds?
ProKit passes -j$(NPROC) by default for parallel make builds. For packages using cmake or other build systems, ensure parallelism is enabled in your override_build rule. If you are iterating on a package, skip the clean step between builds when source files have not changed - prokit build will skip unchanged steps.
Contributing
Frequently Asked Questions
How do I submit a patch?
Use git format-patch to generate patches and send them to the proteanos-dev mailing list. One patch per logical change is the expected format. The commit message should explain what the change does and why - not just what files were touched. If the patch fixes a specific bug, describe the bug and how the patch fixes it.
What coding style is expected?
Match the style of the surrounding code. ProteanOS projects generally follow POSIX shell conventions for scripts and standard C conventions for C code. Tabs for indentation in Makefiles, spaces elsewhere unless the project differs. If in doubt, look at the existing code in the repository you are contributing to - consistency within a project matters more than any universal rule.
How long does patch review take?
Simple, clearly described patches against active repositories are often reviewed within a week. Larger changes, new packages, or modifications to core components take longer because they require more careful review and may need discussion on the list. If a patch has been sitting without feedback for two weeks, a polite follow-up is reasonable.
More Resources
For detailed development information, see:
- Development Hub - overview of development resources
- ProKit documentation - development kit guide
- Source Package Format 2.0 - packaging specification
- Git repositories - source code access