src/rot13/README.md

# ROT13 Example

rot13 (“rotate by 13 places”) takes a message a replaces each letter in the
message with the letter 13th places after it in the alphabet. The rot13 sample
has three parts: a client, a server, and a library defining a FIDL communication
protocol between the components.

## Source layout

- `fidl/`: Contains the definition of a Fuchsia interprocess communication (IPC)
  protocol (`fuchsia.examples.rot13.Rot13`) for a rot13 server and client
  defined as a Fuchsia Interface Definition Language (FIDL) library.
  The `BUILD.gn` file describes how to build the FIDL library that can be used
  as a dependency for the client and server.
- `server/`: Contains the source for the rot13 echo server that takes rot13
  encoded messages, decodes each message, then sends the decoded response back.
  The server handles incoming requests as FIDL messages received from the client.
- `client/`: Contains the source for the rot13 echo client that sends string
  messages to a rot13 server for encoding and prints the results to the system
  log.
- `meta/`: Top-level component realm to perform capability routing between the
  server and client components.

## Before you begin

1.  Start an emulator instance:

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/ffx product-bundle get workstation_eng.qemu-x64
    $ ./third_party/fuchsia-sdk/tools/x64/ffx emu start workstation_eng.qemu-x64
    ```

1.  Start a local package repository instance:

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/fserve --image workstation_eng.qemu-x64-release
    ```

## Build the sample

1.  Run the build script to compile and package the sample:

    ```
    $ ./scripts/build.sh
    ```

1.  Publish the FAR packages to your local package repository:

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/fpublish out/x64/rot13-example.far
    $ ./third_party/fuchsia-sdk/tools/x64/fpublish out/x64/rot13_unittests.far
    ```

## Run the sample

1.  Launch the sample component using `ffx component run`. This resolves the
    component from the package repository and starts it:

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/ffx component run fuchsia-pkg://fuchsia.com/rot13-example#meta/rot13_realm.cm
    ```

1.  View the result messages in the system log using `ffx log`:

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/ffx log --filter rot13
    [rot13_realm/rot13_client] INFO: ***** Message: hello fuchsia has checksum of 1303
    [rot13_realm/rot13_client] INFO: Rotated message is uryyb shpufvn
    [rot13_realm/rot13_client] INFO: unrotated message = hello fuchsia
    ```

1.  Edit the client message using the `args` field in `rot13_client.cml`
    component manifest:

    ```
    {
      program: {
        // ...

        // Program arguments
        args: [
            "-m",
            "hello fuchsia",
        ],
      },
      // ...
    }
    ```

## Run the unit tests

1.  Execute the unit test suite using `ffx test run`. This resolves the
    component from the package repository and executes the tests:

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/ffx test run fuchsia-pkg://fuchsia.com/rot13_unittests#meta/rot13_unittests.cm
    ```

1.  Verify that the test cases pass:

    ```
    Running test 'fuchsia-pkg://fuchsia.com/rot13_unittests#meta/rot13_unittests.cm'
    [RUNNING]	Rot13Test.TrueTest
    [stdout - Rot13Test.TrueTest]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [PASSED]	Rot13Test.TrueTest
    [RUNNING]	Rot13Test.Encrypt_EdgeCases
    [stdout - Rot13Test.Encrypt_EdgeCases]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [PASSED]	Rot13Test.Encrypt_EdgeCases
    [RUNNING]	Rot13Test.Encrypt_HelloWorld
    [stdout - Rot13Test.Encrypt_HelloWorld]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [PASSED]	Rot13Test.Encrypt_HelloWorld
    [RUNNING]	Rot13Test.Encrypt_Empty
    [stdout - Rot13Test.Encrypt_Empty]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [PASSED]	Rot13Test.Encrypt_Empty
    [RUNNING]	Rot13Test.Checksum_Empty
    [stdout - Rot13Test.Checksum_Empty]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [PASSED]	Rot13Test.Checksum_Empty
    [RUNNING]	Rot13Test.Checksum_HelloWorld
    [stdout - Rot13Test.Checksum_HelloWorld]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [PASSED]	Rot13Test.Checksum_HelloWorld

    6 out of 6 tests passed...
    fuchsia-pkg://fuchsia.com/rot13_unittests#meta/rot13_unittests.cm completed with result: PASSED
    ```