github.com/sberex/go-sberex@v1.8.2-0.20181113200658-ed96ac38f7d7/mobile/doc.go (about) 1 // This file is part of the go-sberex library. The go-sberex library is 2 // free software: you can redistribute it and/or modify it under the terms 3 // of the GNU Lesser General Public License as published by the Free 4 // Software Foundation, either version 3 of the License, or (at your option) 5 // any later version. 6 // 7 // The go-sberex library is distributed in the hope that it will be useful, 8 // but WITHOUT ANY WARRANTY; without even the implied warranty of 9 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser 10 // General Public License <http://www.gnu.org/licenses/> for more details. 11 12 // Package geth contains the simplified mobile APIs to go-sberex. 13 // 14 // The scope of this package is *not* to allow writing a custom Sberex client 15 // with pieces plucked from go-sberex, rather to allow writing native dapps on 16 // mobile platforms. Keep this in mind when using or extending this package! 17 // 18 // API limitations 19 // 20 // Since gomobile cannot bridge arbitrary types between Go and Android/iOS, the 21 // exposed APIs need to be manually wrapped into simplified types, with custom 22 // constructors and getters/setters to ensure that they can be meaninfully used 23 // from Java/ObjC too. 24 // 25 // With this in mind, please try to limit the scope of this package and only add 26 // essentials without which mobile support cannot work, especially since manually 27 // syncing the code will be unwieldy otherwise. In the long term we might consider 28 // writing custom library generators, but those are out of scope now. 29 // 30 // Content wise each file in this package corresponds to an entire Go package 31 // from the go-sberex repository. Please adhere to this scoping to prevent this 32 // package getting unmaintainable. 33 // 34 // Wrapping guidelines: 35 // 36 // Every type that is to be exposed should be wrapped into its own plain struct, 37 // which internally contains a single field: the original go-sberex version. 38 // This is needed because gomobile cannot expose named types for now. 39 // 40 // Whenever a method argument or a return type is a custom struct, the pointer 41 // variant should always be used as value types crossing over between language 42 // boundaries might have strange behaviors. 43 // 44 // Slices of types should be converted into a single multiplicative type wrapping 45 // a go slice with the methods `Size`, `Get` and `Set`. Further slice operations 46 // should not be provided to limit the remote code complexity. Arrays should be 47 // avoided as much as possible since they complicate bounds checking. 48 // 49 // If a method has multiple return values (e.g. some return + an error), those 50 // are generated as output arguments in ObjC. To avoid weird generated names like 51 // ret_0 for them, please always assign names to output variables if tuples. 52 // 53 // Note, a panic *cannot* cross over language boundaries, instead will result in 54 // an undebuggable SEGFAULT in the process. For error handling only ever use error 55 // returns, which may be the only or the second return. 56 package geth