|
|
|
# Proposed Structure for the Developer Documentation
|
|
|
|
|
|
|
|
## Introduction
|
|
|
|
|
|
|
|
Introduces the Librem 5. Describes the purpose of this document.
|
|
|
|
|
|
|
|
## Prerequisites, hardware and software
|
|
|
|
|
|
|
|
* What the developer needs in terms of hardware: desktop machine, laptop, etc.
|
|
|
|
* Required software: distro, development environment, connectivity tools, compilers, etc.
|
|
|
|
|
|
|
|
## Setting up Hardware
|
|
|
|
|
|
|
|
### Developer Kit
|
|
|
|
|
|
|
|
Instructions on setting up hardware, plugging in, getting a shell, etc. (issues [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19), [1](https://source.puri.sm/guido.gunther/Apps_Issues/issues/1))
|
|
|
|
|
|
|
|
* Board setup instructions
|
|
|
|
* Document how disk encryption work will work
|
|
|
|
* Document credential retrieval and storage
|
|
|
|
* Document security "omission" (things that will need to be secure
|
|
|
|
* for the phone but aren't yet)
|
|
|
|
|
|
|
|
### Phone
|
|
|
|
|
|
|
|
Cables, physical switches, USB hubs, power, etc.
|
|
|
|
|
|
|
|
## Setting up a Software Development Environment
|
|
|
|
|
|
|
|
### General
|
|
|
|
|
|
|
|
Instructions on setting up development environment(s) (issue [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19))
|
|
|
|
|
|
|
|
### Phone
|
|
|
|
|
|
|
|
Anything that needs to be installed, set up or run on the phone.
|
|
|
|
|
|
|
|
### Workstation
|
|
|
|
|
|
|
|
* GNOME technologies: A run through the various GNOME technologies.
|
|
|
|
* GNOME Builder documentation: Documentation for the GNOME IDE.
|
|
|
|
* Meson: The recommended build system.
|
|
|
|
* Flatpak: Application sandboxing and distribution.
|
|
|
|
* gitg: The GNOME git client.
|
|
|
|
|
|
|
|
Not how to use these, but some information about setting them up, especially
|
|
|
|
for use with the phone - configure connections in SDKs, etc.
|
|
|
|
|
|
|
|
*(A Plasma variant of this only makes sense if phones will ship with Plasma installed. Otherwise, it can wait until later merge requests arrive, in which case the workstation section will get a sibling.)*
|
|
|
|
|
|
|
|
## Application Development
|
|
|
|
|
|
|
|
(Possibly covering development of other kinds of component.)
|
|
|
|
|
|
|
|
### Building
|
|
|
|
|
|
|
|
Instructions on building software (current "App Development" chapter) (issue [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19))
|
|
|
|
|
|
|
|
### Training/Tutorials
|
|
|
|
|
|
|
|
With all of the tools in place, part of the training site can be a walkthrough
|
|
|
|
of making say a hello world app and deploying it to the phone.
|
|
|
|
|
|
|
|
### Examples
|
|
|
|
|
|
|
|
Both C and non-C examples for writing mobile friendly applications for the
|
|
|
|
Librem5. (issue [1](https://source.puri.sm/guido.gunther/Apps_Issues/issues/1))
|
|
|
|
|
|
|
|
### Guidelines/Design
|
|
|
|
|
|
|
|
* List some guidelines for writing apps.
|
|
|
|
* Guidelines for development (like the existing Design page) (issue [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19))
|
|
|
|
|
|
|
|
### Overviews
|
|
|
|
|
|
|
|
#### Phone components
|
|
|
|
|
|
|
|
* How they are used
|
|
|
|
* How they are configured
|
|
|
|
* How they interact with applications
|
|
|
|
|
|
|
|
#### Application interaction with the environment when using the phone
|
|
|
|
|
|
|
|
* Priorities when standard phone features are activated (e.g. incoming calls)
|
|
|
|
* What happens to applications when other events occur, user changes focus?
|
|
|
|
|
|
|
|
#### List of components and how to use them (APIs)
|
|
|
|
|
|
|
|
(These link into reference documentation for each API.)
|
|
|
|
|
|
|
|
See the hardware reference section for a *tentative* list of hardware components.
|
|
|
|
|
|
|
|
Also include software services that *might* be running:
|
|
|
|
|
|
|
|
* Authentication
|
|
|
|
* Contacts
|
|
|
|
* Messaging
|
|
|
|
* Communication
|
|
|
|
|
|
|
|
These may also include system-level services from GNOME:
|
|
|
|
|
|
|
|
* Authentication
|
|
|
|
* ...
|
|
|
|
|
|
|
|
Information about software development that's applicable to the phone, for
|
|
|
|
example, say, descriptions of public phosh/oFono/Calls/virtual keyboard/etc.
|
|
|
|
APIs (issue [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19))
|
|
|
|
|
|
|
|
### API Reference Documentation
|
|
|
|
|
|
|
|
* Catalogue pages linking into the API documentation.
|
|
|
|
* Category pages with additional content.
|
|
|
|
*Not like overviews that would provide more context. These pages group together similar APIs and provide links to overviews as well as API references.*
|
|
|
|
* Generated APIs for components, from middleware up, and anything specific to the phone.
|
|
|
|
*For example, there may be a convenience API for accessing a hardware feature or it may be done via a standard API, but either case would have specific documentation.*
|
|
|
|
|
|
|
|
These contain links out to upstream documentation.
|
|
|
|
|
|
|
|
## Sharing/Publishing
|
|
|
|
|
|
|
|
*(Perhaps part of the previous section/manual.)*
|
|
|
|
|
|
|
|
* Submitting apps to app store/getting apps published:
|
|
|
|
*Once there's an app store in place, we will need to provide a how-to on submitting their apps.* (issue [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19))
|
|
|
|
* Sideloading, testing?
|
|
|
|
|
|
|
|
## Troubleshooting
|
|
|
|
|
|
|
|
Common troubleshooting tips will be listed here.
|
|
|
|
|
|
|
|
*(Perhaps include troubleshooting tips in each relevant section, especially in the early setup sections.)*
|
|
|
|
|
|
|
|
## Getting in Touch
|
|
|
|
|
|
|
|
* Community
|
|
|
|
* Contributing
|
|
|
|
* Report an Issue
|
|
|
|
* FAQ
|
|
|
|
|
|
|
|
*(Perhaps the FAQ would be its own section.)*
|
|
|
|
|
|
|
|
## Appendices
|
|
|
|
|
|
|
|
Where all the internal details are. *("Appendices" doesn't have to be a
|
|
|
|
level itself. The following could all be prefixed by "Appendix" if
|
|
|
|
desired.)*
|
|
|
|
|
|
|
|
### Reference information about hardware
|
|
|
|
|
|
|
|
List of components, their availability (supported by libre drivers) (issues [18](https://source.puri.sm/Librem5/developer.puri.sm/issues/18), [19](https://source.puri.sm/Librem5/developer.puri.sm/issues/19))
|
|
|
|
|
|
|
|
May include, if present and supported:
|
|
|
|
|
|
|
|
* Screen
|
|
|
|
* Speaker
|
|
|
|
* Microphone
|
|
|
|
* Audio jack - headphone, microphone
|
|
|
|
* Modem
|
|
|
|
* WiFi
|
|
|
|
* Bluetooth
|
|
|
|
* Global Navigation Satellite System (GNSS)
|
|
|
|
* Inertial Measurement Unit (IMU)
|
|
|
|
* Accelerometer
|
|
|
|
* Gyroscope
|
|
|
|
* Compass/Magnetometer
|
|
|
|
* Proxity sensor
|
|
|
|
* Ambient light sensor
|
|
|
|
* Camera(s)
|
|
|
|
* SD
|
|
|
|
* USB
|
|
|
|
* WWAN
|
|
|
|
* LEDs
|
|
|
|
* Smart card reader
|
|
|
|
|
|
|
|
### Reference information about software
|
|
|
|
|
|
|
|
* Linux kernel, configuration, drivers, firmware
|
|
|
|
* System services
|
|
|
|
* File system layout, distribution, system locale
|
|
|
|
* User space services, including display servers
|
|
|
|
* Middleware, including toolkits
|
|
|
|
* Applications components (built-in)
|
|
|
|
* Applications (third party) |