diff options
Diffstat (limited to 'mobile/doc.go')
| -rw-r--r-- | mobile/doc.go | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/mobile/doc.go b/mobile/doc.go new file mode 100644 index 000000000..50cc7f4f8 --- /dev/null +++ b/mobile/doc.go @@ -0,0 +1,57 @@ +// Copyright 2016 The go-ethereum Authors +// This file is part of the go-ethereum library. +// +// The go-ethereum library is free software: you can redistribute it and/or modify +// it under the terms of the GNU Lesser General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// The go-ethereum library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License +// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>. + +// Package geth contains the simplified mobile APIs to go-ethereum. +// +// The scope of this package is *not* to allow writing a custom Ethereun client +// with pieces plucked from go-ethereum, rather to allow writing native dapps on +// mobile platforms. Keep this in mind when using or extending this package! +// +// API limitations +// +// Since gomobile cannot bridge arbitrary types between Go and Android/iOS, the +// exposed APIs need to be manually wrapped into simplified types, with custom +// constructors and getters/setters to ensure that they can be meaninfully used +// from Java/ObjC too. +// +// With this in mind, please try to limit the scope of this package and only add +// essentials without which mobile support cannot work, especially since manually +// syncing the code will be unwieldy otherwise. In the long term we might consider +// writing custom library generators, but those are out of scope now. +// +// Content wise each file in this package corresponds to an entire Go package +// from the go-ethereum repository. Please adhere to this scoping to prevent this +// package getting unmaintainable. +// +// Wrapping guidelines: +// +// Every type that is to be exposed should be wrapped into its own plain struct, +// which internally contains a single field: the original go-ethereum version. +// This is needed because gomobile cannot expose named types for now. +// +// Whenever a method argument or a return type is a custom struct, the pointer +// variant should always be used as value types crossing over between language +// boundaries might have strange behaviors. +// +// Slices of types should be converted into a single multiplicative type wrapping +// a go slice with the methods `Size`, `Get` and `Set`. Further slice operations +// should not be provided to limit the remote code complexity. Arrays should be +// avoided as much as possible since they complicate bounds checking. +// +// Note, a panic *cannot* cross over language boundaries, instead will result in +// an undebuggable SEGFAULT in the process. For error handling only ever use error +// returns, which may be the only or the second return. +package geth |