Dev Docs
This commit is contained in:
parent
049308bee3
commit
8139814fe7
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: Cwtch Developer Documentation
|
||||
description: " In this development log we will highlight some of the major documentation updates over the last few weeks."
|
||||
slug: cwtch-developer-documentation
|
||||
tags: [cwtch, cwtch-stable, developer-documentation, security-handbook]
|
||||
image: /img/devlog9_small.png
|
||||
hide_table_of_contents: false
|
||||
toc_max_heading_level: 4
|
||||
authors:
|
||||
- name: Sarah Jamie Lewis
|
||||
title: Executive Director, Open Privacy Research Society
|
||||
image_url: /img/sarah.jpg
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
## Cwtch Development Handbook
|
||||
|
||||
We have created a new documentation section, [the developers handbook](/developing/intro). This new section is targeted towards to people working on Cwtch projects (e.g. the official Cwtch library or the Cwtch UI), as well as people who want to build new Cwtch applications (e.g. chat bots or custom clients).
|
||||
|
||||
### Release and Packaging Process
|
||||
|
||||
The new handbook features a breakdown of [Cwtch release processes](/developing/release) - describing what, and how, build artifacts are created; the difference between nightly and official builds; how the official release process works; and how reproducible build scripts are created.
|
||||
|
||||
### Cwtch Application Development
|
||||
|
||||
For the first time ever we now have [comprehensive documentation on how to build a Cwtch Application](/developing/category/building-a-cwtch-app). This section of the development handbook covers everything from [choosing a Cwtch library](/developing/building-a-cwtch-app/intro#choosing-a-cwtch-library), to [building your first application](/developing/building-a-cwtch-app/building-an-echobot).
|
||||
|
||||
|
||||
## Help us go further!
|
||||
|
||||
We couldn't do what we do without all the wonderful community support we get, from [one-off donations](https://openprivacy.ca/donate) to [recurring support via Patreon](https://www.patreon.com/openprivacy).
|
||||
|
||||
If you want to see us move faster on some of these goals and are in a position to, please [donate](https://openprivacy.ca/donate). If you happen to be at a company that wants to do more for the community and this aligns, please consider donating or sponsoring a developer.
|
||||
|
||||
Donations of **$5 or more** can opt to receive stickers as a thank-you gift!
|
||||
|
||||
For more information about donating to Open Privacy and claiming a thank you gift [please visit the Open Privacy Donate page](https://openprivacy.ca/donate/).
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"label": "Developers Handbook",
|
||||
"position": 10,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"label": "Building a Cwtch App",
|
||||
"position": 10,
|
||||
"link": {
|
||||
"type": "generated-index"
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,83 @@
|
|||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Building a Cwtch Echobot
|
||||
|
||||
In this tutorial we will walk through building a simple Cwtch Echobot. A bot that, when messaged, simply responds with the message it was sent.
|
||||
|
||||
For completeness, we will build an Echobot in multiple difference Cwtch frameworks to get a feel for the different levels of functionality offered by each library or
|
||||
framework.
|
||||
|
||||
## Using CwtchBot (Go)
|
||||
|
||||
:::info CwtchBot Framework
|
||||
|
||||
This tutorial uses the CwtchBot framework.
|
||||
:::
|
||||
|
||||
Start by creating a new Go project, and a file `main.go`. In the `main` function:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"cwtch.im/cwtch/event"
|
||||
"cwtch.im/cwtch/model"
|
||||
"cwtch.im/cwtch/protocol/connections"
|
||||
"git.openprivacy.ca/sarah/cwtchbot"
|
||||
_ "github.com/mutecomm/go-sqlcipher/v4"
|
||||
"os/user"
|
||||
"path"
|
||||
)
|
||||
|
||||
func main() {
|
||||
|
||||
// Set up a new Cwtch Profile in $HOME/.echobot
|
||||
user, _ := user.Current()
|
||||
cwtchbot := bot.NewCwtchBot(path.Join(user.HomeDir, "/.echobot/"), "echobot")
|
||||
|
||||
// Launch the Cwtch Bot
|
||||
cwtchbot.Launch()
|
||||
|
||||
// Echobot Cwtch Address will be printed to stdout
|
||||
fmt.Printf("echobot address: %v", cwtchbot.Peer.GetOnion())
|
||||
|
||||
// Start of the eventbus loop
|
||||
for {
|
||||
message := cwtchbot.Queue.Next()
|
||||
cid, _ := cwtchbot.Peer.FetchConversationInfo(message.Data[event.RemotePeer])
|
||||
switch message.EventType {
|
||||
case event.NewMessageFromPeer:
|
||||
// Send an Acknowledgement of the Message
|
||||
cwtchbot.Queue.Publish(event.NewEvent(event.PeerAcknowledgement, map[event.Field]string{event.EventID: message.EventID, event.RemotePeer: message.Data[event.RemotePeer]}))
|
||||
// Unpack the message
|
||||
msg := cwtchbot.UnpackMessage(message.Data[event.Data])
|
||||
// Print the message to stdout...
|
||||
fmt.Printf("Message: %v", msg)
|
||||
// Repackage the message, and reply...
|
||||
reply := string(cwtchbot.PackMessage(msg.Overlay, msg.Data))
|
||||
cwtchbot.Peer.SendMessage(cid.ID, reply)
|
||||
case event.PeerStateChange:
|
||||
state := message.Data[event.ConnectionState]
|
||||
// If we have a new peer that is authenticated....
|
||||
if state == connections.ConnectionStateName[connections.AUTHENTICATED] {
|
||||
// accept the stranger as a new contact
|
||||
cwtchbot.Peer.NewContactConversation("stranger", model.DefaultP2PAccessControl(), true)
|
||||
}
|
||||
default:
|
||||
// Other events will be handled here...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Using Imp (Rust)
|
||||
|
||||
:::info Imp (Rust) Bot Framework
|
||||
|
||||
This tutorial uses the Imp Cwtch Bot framework (Rust).
|
||||
:::
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Core Concepts
|
||||
|
||||
This page documents the core concepts that you, as a Cwtch App Developer, will encounter fairly frequently.
|
||||
|
||||
## Cwtch Home Directory
|
||||
|
||||
Often referred to as `$CWTCH_HOME`, the Cwtch application home directory is the location where Cwtch stores all information from a Cwtch application.
|
||||
|
||||
## Profiles
|
||||
|
||||
Cwtch profiles are saved as encrypted sqlite3 databases. You will rarely/never have to interact directly with the database. Instead eahc library provides a set of interfaces overwhich
|
||||
|
||||
## The Event Bus
|
||||
|
||||
Regardless of which library you end up choosing, the one constant interface you will have to get used to is the EventBus. Cwtch handles all asynchronous tasks (e.g. receiving a message from a peer) automatically, eventually placing a message on the EventBus. Application can subscribe to certain kinds of messages e.g. `NewMessageFromPeer` and setup an event handler to run code in response to such a message.
|
||||
|
||||
For an example see the Echo Bot tutorial.
|
||||
|
||||
## Settings
|
||||
|
||||
### Experiments
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Getting Started
|
||||
|
||||
## Choosing A Cwtch Library
|
||||
|
||||
### Cwtch Go Lib
|
||||
|
||||
The official Cwtch library is written in Go and can be found at [https://git.openprivacy.ca/cwtch.im/cwtch](https://git.openprivacy.ca/cwtch.im/cwtch). This library allows access to all Cwtch functionality.
|
||||
|
||||
### CwtchBot
|
||||
|
||||
We also provide a specialized Cwtch Bot framework in Go that provides a more lightweight and tailored approach to building chat bots. For an introduction to building chatbots with the CwtchBot framework check out the [building an echobot tutorial](/developing/building-a-cwtch-app/building-an-echobot#using-cwtchbot-go).
|
||||
|
||||
### Autobindings (C-bindings)
|
||||
|
||||
The [official c-bindings for Cwtch](https://git.openprivacy.ca/cwtch.im/autobindings) are automatically generated from the Cwtch Go Library. The API is limited compared to accessing the Cwtch Go Library directly, and is explicitly tailored towards building the Cwtch UI.
|
||||
|
||||
### libCwtch-rs (Rust)
|
||||
|
||||
An experimental rust-fied version of Cwtch Autobindings is available in [libCwtch-rs](https://crates.io/crates/libcwtch). While we have plans to officially adopt rust bindings in the future, right now Rust support lags behind the rest of the Cwtch ecosystem.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Introduction to Cwtch Development
|
||||
|
||||
- [Core Concepts](/developing/building-a-cwtch-app/core-concepts)
|
||||
- [Security Handbook](/security/intro)
|
||||
|
||||
## Contributing to Cwtch Core
|
||||
|
||||
- [Release and Packaging Process](/developing/release)
|
||||
|
||||
## Building Cwtch Bots
|
||||
|
||||
- [Choosing a Library](/developing/building-a-cwtch-app/intro#choosing-a-cwtch-library)
|
||||
- [Echobot Tutorial](/developing/building-a-cwtch-app/building-an-echobot)
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Release and Packaging Process
|
||||
|
||||
Cwtch builds are automatically constructed via Drone. In order to be built the tasks must be approved by a project team member.
|
||||
|
||||
## Automated Testing
|
||||
|
||||
Drone carries out a suite of automated tests at various stages of the release pipeline.
|
||||
|
||||
| Test Suite | Repository | Notes |
|
||||
|-----------------------------|------------------|---------------------------------------------------------------------------------------------------------------|
|
||||
| Integration Test | cwtch.im/cwtch | A full exercise of peer-to-peer and group messaging |
|
||||
| File Sharing Test | cwtch.im/cwtch | Tests that file sharing and image downloading work as expected |
|
||||
| Automated Download Test | cwtch.im/cwtch | Tests that automated image downloading (e.g. profile pictures) work as expected |
|
||||
| UI Integration Test | cwtch.im/cwtch-ui| A suite of Gherkin tests to exercise various UI flows like Creating / Deleting profiles and changing settings |
|
||||
|
||||
## Cwtch Autobindings
|
||||
|
||||
Drone produces the following build artifacts for all Cwtch autobindings builds.
|
||||
|
||||
| Build Artifact | Platform | Notes |
|
||||
|------------------------------|----------|------------------------------------------------------------|
|
||||
| android/cwtch-sources.jar | Android | gomobile derived source code for the Android Cwtch library |
|
||||
| android/cwtch.aar | Android | Android Cwtch library. Supports arm, arm64, and amd64. |
|
||||
| linux/libCwtch.h | Linux | C header file |
|
||||
| linux/libCwtch.so | Linux | x64 shared library |
|
||||
| windows/libCwtch.h | Windows | C header file |
|
||||
| windows/libCwtch.dll | Windows | x64 bit shared library |
|
||||
| macos/libCwtch.arm64.dylib | MacOS | Arm64 shared library |
|
||||
| macos/libCwtch.x64.dylib | MacOS | x64 shared library |
|
||||
|
||||
## UI Nightly Builds
|
||||
|
||||
We make unreleased versions of Cwtch available for testing as [Cwtch Nightlies](/docs/contribute/testing#cwtch-nightlies).
|
||||
|
||||
Each nightly build folder contains a collection of build artifacts e.g. (APK files for Android, installer executables for Android) in single convenient folder. A full list of build artifacts currently produced is as follows:
|
||||
|
||||
| Build Artifact | Platform | Notes |
|
||||
|-----------------------------|----------|----------------------------------------------------------------------------------------|
|
||||
| cwtch-VERSION.apk | Android | Supports arm, arm64, and amd64. Can be sideloaded. |
|
||||
| cwtch-VERSION.aab | Android | Android App Bundle for publishing to appstores |
|
||||
| Cwtch-VERSION.dmg | MacOS | |
|
||||
| cwtch-VERSION.tar.gz | Linux | Contains the code, libs, and assets in addition to install scripts for various devices |
|
||||
| cwtch-VERSION.zip | Windows | |
|
||||
| cwtch-installer-VERSION.exe | Windows | NSIS powered installation wizard |
|
||||
|
||||
Nightly builds are regularly purged from the system
|
||||
|
||||
## Official Releases
|
||||
|
||||
The Cwtch Team meets on a regular basis and reaches consensus based on nightly testing feedback and project roadmaps.
|
||||
|
||||
When the decision is made to cut a release build, a nightly version is built with a new git tag reflecting the release version e.g. `v.1.12.0`. The build artifacts are then copied to the Cwtch release website to a dedicated versioned folder.
|
||||
|
||||
### Reproducible Builds
|
||||
|
||||
We use [repliqate](https://git.openprivacy.ca/openprivacy/repliqate) to provide [reproducible build scripts for Cwtch](https://git.openprivacy.ca/cwtch.im/repliqate-scripts).
|
||||
|
||||
We update the `repliqate-scripts` repository with scripts for all official releases. Currently only Cwtch bindings are reproducible
|
||||
|
|
@ -89,6 +89,11 @@ const config = {
|
|||
position: 'left',
|
||||
label: 'Security Handbook',
|
||||
},
|
||||
{
|
||||
to: '/developing/intro',
|
||||
position: 'left',
|
||||
label: 'Developers Handbook',
|
||||
},
|
||||
{
|
||||
to: 'blog',
|
||||
position: 'left',
|
||||
|
|
@ -129,6 +134,10 @@ const config = {
|
|||
to: '/security/intro',
|
||||
label: 'Security Handbook',
|
||||
},
|
||||
{
|
||||
to: '/developing/intro',
|
||||
label: 'Developer Guide',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
|
|
@ -185,6 +194,17 @@ const config = {
|
|||
rehypePlugins: [katex],
|
||||
},
|
||||
],
|
||||
[
|
||||
'@docusaurus/plugin-content-docs',
|
||||
{
|
||||
id: 'docs-developer',
|
||||
path: 'developing',
|
||||
routeBasePath: 'developing',
|
||||
sidebarPath: require.resolve('./sidebars.js'),
|
||||
remarkPlugins: [math],
|
||||
rehypePlugins: [katex],
|
||||
},
|
||||
],
|
||||
],
|
||||
stylesheets: [
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in New Issue