github.com/astaguna/popon-core@v0.0.0-20231019235610-96e42d76a5ff/ClientLibrary/README.md (about)

     1  # Psiphon Client Library README
     2  
     3  ## Mobile
     4  
     5  If you are planning to embed Psiphon in a mobile application, please use the [MobileLibrary](../MobileLibrary).
     6  
     7  ## Using the Library in your App
     8  
     9  **First step:** Review the sample code, located under `example`.
    10  This code provides an example of how to correctly use the client library.
    11  
    12  **Second step:** Review the comments for `Start` and `Stop` in [`PsiphonTunnel.go`](PsiphonTunnel.go). They describe the client interface.
    13  
    14  ## Building for Darwin (iOS, MacOS)
    15  
    16  Note that you will need to have Xcode installed on a machine running MacOS.
    17  
    18  ##### Run the build:
    19  
    20  *Ensure that the command below is run from within the `ClientLibrary` directory*
    21  
    22  ```
    23  ./build-darwin.sh all
    24  ```
    25  
    26  This command can also be modified by:
    27   - replacing `all` with `ios` or `macos` as the first parameter to `build-darwin.sh` (as in `./build-darwin.sh ios`) to only build binaries for the operating system of choice
    28  
    29  When that command completes, the compiled binaries will be located in the `build` directory. The structure will be:
    30  
    31  ```
    32  build
    33  └── darwin
    34      └── ios
    35      │   └── PsiphonTunnel-ios-arm.h
    36      │   └── PsiphonTunnel-ios-arm.dylib
    37      │   └── PsiphonTunnel-ios-arm64.h
    38      │   └── PsiphonTunnel-ios-arm64.dylib
    39      └── macos
    40          └── PsiphonTunnel-macos-386.dylib
    41          └── PsiphonTunnel-macos-386.dylib
    42          └── PsiphonTunnel-macos-amd64.dylib
    43          └── PsiphonTunnel-macos-amd64.dylib
    44  ```
    45  
    46  ## Building with Docker (Android, Linux, Windows)
    47  
    48  Note that you may need to use `sudo docker` below, depending on your OS.
    49  
    50  ##### Create the build image:
    51  
    52  1. While in the `ClientLibrary` directory, run the command: `docker build --no-cache=true -t psiclientlibrary-builder .`
    53  
    54  2. Once completed, verify that you see an image named `psiclientlibrary-builder` when running: `docker images`
    55  
    56  ##### Run the build:
    57  
    58  *Ensure that the command below is run from within the `ClientLibrary` directory*
    59  
    60  *The `--user "$(id -u):$(id -g)"` flag must be omitted when building on macOS because manually specifying the UID/GID will cause the build to fail since Docker on macOS handles host to container UID/GID mapping automatically and will be unable to map the manually specified UID/GID to the current user.*
    61  
    62  ```bash
    63  cd .. && \
    64    docker run \
    65    --platform=linux/amd64 \
    66    --user "$(id -u):$(id -g)" \
    67    --rm \
    68    -v $PWD:/go/src/github.com/astaguna/popon-core \
    69    psiclientlibrary-builder \
    70    /bin/bash -c './make.bash all' \
    71  ; cd -
    72  ```
    73  
    74  This command can also be modified by:
    75   - replacing `all` with `android`, `linux`, or `windows` as the first parameter to `make.bash` (as in `./make.bash windows`) to only build binaries for the operating system of choice
    76  
    77  When that command completes, the compiled binaries will be located in the `build` directory (`./build`, and everything under it will likely be owned by root, so be sure to `chown` to an appropriate user) under the current directory. The structure will be:
    78  
    79  ```
    80  build
    81  ├── android
    82  │   └── PsiphonTunnel-android-arm7.h
    83  │   └── PsiphonTunnel-android-arm7.so
    84  │   └── PsiphonTunnel-android-arm64.h
    85  │   └── PsiphonTunnel-android-arm64.so
    86  ├── linux
    87  │   └── PsiphonTunnel-linux-386.h
    88  │   └── PsiphonTunnel-linux-386.so
    89  │   └── PsiphonTunnel-linux-amd64.h
    90  │   └── PsiphonTunnel-linux-amd64.so
    91  └── windows
    92      └── PsiphonTunnel-windows-386.h
    93      └── PsiphonTunnel-windows-386.dll
    94      └── PsiphonTunnel-windows-amd64.h
    95      └── PsiphonTunnel-windows-amd64.dll
    96  ```