1# Network Simulator Development 2 3This section walks you through building netsim from source. 4 5Netsim can be built as part of emulator or cuttlefish and best practice is to 6setup both and switch between repo directories to test each build environment. 7 8* To build with emulator, follow the [netsim with emulator](#netsim_with_emulator) 9section to build netsim by `cmake` in `emu-master-dev` and `netsim-dev` manifest branch. 10 11* To build with cuttlefish, follow the [netsim with 12cuttlefish](#netsim_with_cuttlefish) to build netsim by `soong` in `aosp-main` 13manifest branch. 14 15## Emulator and cuttlefish build branches 16 17The *netsim* network simulator is built as a component of 18[emulator](https://source.android.com/docs/setup/create/avd) 19and 20[cuttlefish](https://source.android.com/docs/setup/create/cuttlefish) 21virtual devices. 22 23*Emulator* allows you to run emulations of Android devices on Windows, macOS or 24Linux machines. Emulator runs the Android operating system in a virtual machine 25called an Android Virtual Device (AVD). 26The emulator is typically used from 27[Android Studio](https://developer.android.com/studio). 28 29*Cuttlefish* is a configurable virtual Android device that can be run on Linux 30x86 machines both remotely (using third-party cloud offerings such as Google 31Cloud Engine) and locally. Cuttlefish runs the Android operating system in a 32virtual machine called a Cuttlefish Virtual Device (CVD). 33Cuttlefish is typically used by developers working with AOSP code to [launch 34AOSP builds](https://source.android.com/docs/setup/create/cuttlefish-use). 35 36The table below summarizes the two virtual device environments: 37 38| | emulator | cuttlefish | 39|:----------------|:------------------------------------:|:----------------: | 40| AOSP branch | `emu-master-dev` & `netsim-dev` | `aosp-main` | 41| launcher | `emulator` app and<br>Android Studio | `launch_cvd` and<br>`cvd` app | 42| best for | App developer | Platform developer | 43| Supported OS | Linux, MacOS, Windows | Linux | 44| Build system | CMake (CMakeLists.txt) | Soong (Android.bp) | 45| Virtual device | AVD | CVD | 46 47Netsim is the default networking backplane for AVD and CVD emulated Android 48devices. 49 50## <a name="netsim_with_emulator"></a>Build netsim with emulator 51 52For developing netsim alongside emulator, start with the OS specific build 53instructions: 54* [Android emulator Windows Development]( 55https://android.googlesource.com/platform/external/qemu/+/refs/heads/emu-master-dev/android/docs/WINDOWS-DEV.md 56) 57* [Android emulator MacOS Development]( 58https://android.googlesource.com/platform/external/qemu/+/refs/heads/emu-master-dev/android/docs/DARWIN-DEV.md 59) 60* [Android emulator Linux Development]( 61https://android.googlesource.com/platform/external/qemu/+/refs/heads/emu-master-dev/android/docs/LINUX-DEV.md 62) 63 64In general changes should be built and tested on all three operating systems. 65 66Follow the instructions above links for workstation setup. 67 68### Initialize and sync the code 69 70Download the emu-master-dev branch: 71 72``` 73mkdir /repo/emu-master-dev; cd /repo/emu-master-dev 74repo init -u https://android.googlesource.com/platform/manifest -b emu-master-dev 75``` 76Sync the source code: 77 78``` 79repo sync -j8 80``` 81 82### Emulator full build 83 84Use Android emulator toolchain script to run the build: 85``` 86cd /repo/emu-master-dev/external/qemu 87sh android/rebuild.sh --gfxstream 88``` 89 90The output can be found in: 91``` 92/repo/emu-master-dev/external/qemu/objs/distribution/emulator 93``` 94 95### Netsim incremental build 96 97Currently the netsim binaries in 98`/repo/emu-master-dev/prebuilts/android-emulator-build/common/netsim/*` does get weekly updates with the latest binary. If you want to build netsim from source, you must sync and build from a separate branch `netsim-dev`. 99 100Download the netsim-dev branch: 101 102``` 103mkdir /repo/netsim-dev; cd /repo/netsim-dev 104repo init -u https://android.googlesource.com/platform/manifest -b netsim-dev 105``` 106Sync the source code: 107 108``` 109repo sync -j8 110``` 111 112The `emulator` rebuild script does a complete clean build of all emulator components. 113For incrmental builds of the `netsimd` component, you can use the `cmake_setup` script: 114``` 115cd /repo/netsim-dev/tools/netsim 116scripts/build_tools.py --task configure compileinstall 117``` 118 119If the build fails with rust errors it may be necessary to issue this command: 120 121``` 122rm rust/Cargo.lock 123``` 124 125The output can be found in 126 127``` 128/repo/netsim-dev/tools/netsim/objs/distribution/emulator 129``` 130 131You can copy the netsim binaries into `emu-master-dev` 132 133``` 134cp -r /repo/netsim-dev/tools/netsim/objs/distribution/emulator/* /repo/emu-master-dev/external/qemu/objs/distribution/emulator 135``` 136 137## <a name="netsim_with_cuttlefish"></a>Build netsim with cuttlefish 138 139The [Android Developer Codelab](https://source.android.com/docs/setup/start) 140provides instructions for building and running cuttlefish AVDs. 141 142Follow the instructions in the codelab for workstation setup. 143 144### Initialize and sync the code 145 146Initialize the repo: 147``` 148mkdir /repo/aosp-main; cd /repo/aosp-main 149repo init -u https://android.googlesource.com/platform/manifest -b aosp-main 150``` 151 152Sync the source code: 153``` 154repo sync -j8 155``` 156 157### Build cuttlefish 158 159Set up build environment: 160``` 161source build/envsetup.sh 162``` 163 164Set the target device type: 165``` 166lunch aosp_cf_x86_64_phone 167``` 168 169Start the build: 170``` 171m -j64 172``` 173 174The netsim executable can be found in: 175``` 176/repo/aosp-main/out/host/linux-x86/bin 177``` 178 179### Cuttlefish incremental netsim build 180 181 182Start the build with netsimd target: 183``` 184m netsimd -j64 185``` 186 187## Unit Testing 188 189Unit tests can be run from the `aosp-main` branch using the `atest` command: 190``` 191atest --host-unit-test-only --test-filter netsim 192``` 193 194Unit tests can be run from the `netsim-dev` branch using the following command 195``` 196scripts/build_tools.py --task runtest 197``` 198 199### Repo workflow 200 201The repo workflow for creating and uploading a change request: 202``` 203repo start new-branch 204git add <files> 205git commit 206repo upload --branch=new-branch 207``` 208 209Subsequent commits: 210``` 211git add <files> 212git commit --amend --no-edit 213repo upload --branch=new-branch 214``` 215 216## Documentation 217 218The developer and user documentation for netsim is stored in the `guide` 219directory in `mdbook` format. Refer to 220[install](https://rust-lang.github.io/mdBook/guide/installation.html) 221for instructions on how to install `mdbook`. 222 223Use this command to start a local web server with the netsim guide: 224``` 225mdbook serve guide 226``` 227 228