src/calculator/README.md

# Calculator Example

Calculator provides an interface for client components to request compute
operations over IPC using FIDL. The calculator sample has three parts:
the engine, a client, 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.calculator.Calculator`) 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 engine.
- `engine/`: Contains the source for the calculator engine that accepts compute
  operations and sends the results back.
  The engine handles incoming requests as FIDL messages received from the client.
- `client/`: Contains the source for the client that sends compute requests to
  the calculator engine then prints the results to the system log.
- `meta/`: Top-level component realm to perform capability routing between the
  engine and client components.

## Before you begin

1.  Start a FEMU instance:

    ```
    $ ./third_party/fuchsia-sdk/bin/femu.sh -N
    ```

1.  Start a local package repository instance:

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

## Build the sample

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

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

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

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/fpublish out/x64/calculator-example.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/calculator-example#meta/calculator_realm.cm
    ```

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

    ```
    $ ./third_party/fuchsia-sdk/tools/x64/ffx target log watch
    [calculator_realm/client] INFO: Request: 2 + 2
    [calculator_realm/client] INFO: Result: 4
    ```

## 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/engine_unittest#meta/engine_unittest.cm
    ```

1.  Verify that the test cases pass:

    ```
    Running test 'fuchsia-pkg://fuchsia.com/engine_unittest#meta/engine_unittest.cm'
    [RUNNING]	main
    [stdout - main]
    Running main() from ../../third_party/googletest/src/googletest/src/gtest_main.cc
    [==========] Running 5 tests from 1 test suite.
    [----------] Global test environment set-up.
    [----------] 5 tests from EngineUnitTest
    [ RUN      ] EngineUnitTest.Negate
    [       OK ] EngineUnitTest.Negate (11 ms)
    [ RUN      ] EngineUnitTest.Add
    [       OK ] EngineUnitTest.Add (12 ms)
    [ RUN      ] EngineUnitTest.Subtract
    [       OK ] EngineUnitTest.Subtract (12 ms)
    [ RUN      ] EngineUnitTest.Multiply
    [       OK ] EngineUnitTest.Multiply (11 ms)
    [ RUN      ] EngineUnitTest.Divide
    [       OK ] EngineUnitTest.Divide (11 ms)
    [----------] 5 tests from EngineUnitTest (60 ms total)

    [----------] Global test environment tear-down
    [==========] 5 tests from 1 test suite ran. (66 ms total)
    [  PASSED  ] 5 tests.
    [PASSED]	main

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