diff --git a/docs/nix_dev_env.md b/docs/nix_dev_env.md index f3dff9f63..cf5281688 100644 --- a/docs/nix_dev_env.md +++ b/docs/nix_dev_env.md @@ -1,138 +1,139 @@ # Motivation We use Nix to package all of the dependencies for our dev environment. It does several things for us: - Enables new devs on macOS or Linux to set up our dev environment with just one command - Makes sure that everybody on the team is using the same versions of all the tools - Allows us to isolate development dependencies from affecting the host system For how Nix package management works, please refer to the official [how Nix works guide](https://nixos.org/guides/how-nix-works.html). # Supported workflows Some workflows require additional steps after the Nix installation. These steps are documented in [Workflow prerequisites](#workflow-prerequisites). | Workflow | macOS supported | | ------------------------------- | --------------- | | `keyserver` (Node.js) | ✅ | | `web` & `landing` (Webpack) | ✅ | | `native` iOS (React Native) | ✅ | | `native` Android (React Native) | ✅ | | C++ services | ❌ **\*** | | Rust services | ✅ | **\*** Workflow requires documentation; and it requires the RabbitMQ and AWS/Localstack services to be available. # Requirements To set up a dev environment using Nix, you will need a macOS or Linux machine. # Prerequisites ## Xcode Command Line Tools For developers using macOS, you need to make sure that the Xcode “Command Line Tools” are installed. You can do this by running: ``` xcode-select --install ``` ### Xcode For developers using macOS, go to the [Mac App Store](https://apps.apple.com/us/app/xcode/id497799835) to install Xcode; or if you already have it, update it to the latest version. Once Xcode is installed, open it up. If you are prompted, follow the instructions to install any [“Additional Required Components”](./nix_mobile_setup.md#xcode-settings) ## Nix package manager To install and configure the [Nix package manager](https://nixos.org), please run: ``` # Pull down Git repository git clone git@github.com:CommE2E/comm.git cd comm # Install Nix and Comm binary cache ./scripts/install_nix.sh ``` Now either close and reopen your terminal window or re-source your shell configuration file in order to have changes applied. ## Install development dependencies As a first step, you’ll want to set up the JavaScript environment and pull in all necessary NPM packages. Run the following command: ``` # Create development shell nix develop # Install yarn dependencies yarn cleaninstall ``` ## Workflow specific prerequisites On macOS, [installing Xcode](./nix_mobile_setup.md#xcode) is a prerequisite for all workflows. - [Web prerequisites](./nix_web_setup.md#nix-web-requisities) - [React Dev Tools Chrome extension](./nix_web_setup.md#react-dev-tools-chrome-extension) - [Redux Dev Tools Chrome extension](./nix_web_setup.md#redux-dev-tools-chrome-extension) - [Mobile prerequisites](./nix_mobile_setup.md#nix-mobile-prerequisites) - [iOS development](./nix_mobile_setup.md#ios-development) - [Xcode settings](./nix_mobile_setup.md#xcode-settings) - [Android development](./nix_mobile_setup.md#android-development) - [JDK (Java Development Kit)](./nix_mobile_setup.md#jdk) - [Android Studio](./nix_mobile_setup.md#android-studio) - [Android SDK](./nix_mobile_setup.md#android-sdk) - [Android emulator](./nix_mobile_setup.md#android-emulator) - [Debugging tools](./nix_mobile_setup.md#debugging-tools) - [Reactotron](./nix_mobile_setup.md#reactotron) # Development environment Run `nix develop` to create a dev environment. Nix will handle the installation of all remaining dependencies not mentioned in [Workflow prerequisites](#workflow-prerequisites). ## Development workflows - [Web workflows](./nix_web_workflows.md#development) - [Flow typechecker](./nix_web_workflows.md#flow-typechecker) - [Running keysever](./nix_web_workflows.md#running-keyserver) - [Running web app](./nix_web_workflows.md#running-web-app) - [Running landing page](./nix_web_workflows.md#running-landing-page) - [Debugging](./nix_web_workflows.md#debugging) - [React Developer Tools](./nix_web_workflows.md#react-developer-tools) - [Redux Developer Tools](./nix_web_workflows.md#redux-developer-tools) - [Debugging JavaScript](./nix_web_workflows.md#debugging-javascript) - [Mobile workflows](./nix_mobile_workflows.md#mobile-workflows) - [Running mobile app on iOS Simulator](./nix_mobile_workflows.md#running-mobile-app-on-ios-simulator) - [Running mobile app on Android Emulator](./nix_mobile_workflows.md#running-mobile-app-on-android-emulator) - [Running mobile app on physical iOS devices](./nix_mobile_workflows.md#running-mobile-app-on-physical-ios-devices) - [Shared workflows](./nix_shared_workflows.md#shared-workflows) - [Inspect database with TablePlus](./nix_shared_workflows.md#inspect-database-with-tableplus) - [Codegen](./nix_shared_workflows.md#codegen) - [Codegen for JSI](./nix_shared_workflows.md#codegen-for-jsi) - [Working with Phabricator](./nix_shared_workflows.md#working-with-phabricator) + - [Setup](./nix_shared_workflows.md#setup) - [Creating a new diff](./nix_shared_workflows.md#creating-a-new-diff) - [Updating a diff](./nix_shared_workflows.md#updating-a-diff) - [Working with a stack](./nix_shared_workflows.md#working-with-a-stack) - [Committing a diff](./nix_shared_workflows.md#committing-a-diff) - [Final notes](./nix_shared_workflows.md#final-notes) ## Using alternate shells with Nix Alternate shells such as zsh or fish can also be used with Nix. To use an alternate shell, run: ```sh nix develop -c $SHELL ``` You may also replace the bash shell with the shell of your preference. ```sh nix develop exec zsh # or fish ``` ## How Nix introduces dependencies to a development environment Nix installs packages in the Nix store at package-specific paths (e.g. `/nix/store/x7kdiasp...-clang/bin/clang`). When you run `nix develop`, Nix sets environment variables such as `PATH` to expose the binary dependencies to your shell. This model can be extended through shell hooks to support other build toolchains such as `pkg-config`, `cmake`, and many other language specific package managers by simply adding the respective toolchain to `nativeBuildInputs`. diff --git a/docs/nix_shared_workflows.md b/docs/nix_shared_workflows.md index 0a04a3f09..a45d5b96b 100644 --- a/docs/nix_shared_workflows.md +++ b/docs/nix_shared_workflows.md @@ -1,83 +1,83 @@ # Shared workflows ## Inspect database with TablePlus Feel free to use any MariaDB administration platform that you’re comfortable with. PHP was deprecated in macOS 12 (Monterey), leading many of us to switch to [TablePlus](https://tableplus.com/). After running `nix develop` which will create a MariaDB instance, you need to open a new connection. After opening TablePlus, click the “Create a new connection” text at the bottom of the window that appears. - Alternatively, you can navigate through Connection → New... in the menu at the top of the display. Choose MariaDB from the database options that appear. You’ll be prompted for: - Name (Comm) - Check “Use socket”. Enter socket path: (`/Users//.local/share/MariaDB/mysql.sock`, substituting `` for your user. `` can be found by running `echo $USER` in a terminal) ## Codegen We use a couple of tools that automatically generate code. There is always a source of truth – usually some file(s) with schemas. ### Codegen for JSI JSI is a framework in React Native that allows C++ and JS to communicate synchronously and directly. The codegen for JSI takes a Flow schema and generates C++ files that enable communication between JS and C++ in `react-native` apps. The script to generate this code is written in JavaScript and is included as a npm package so no additional software is needed to use it. The schema has to be defined in Flow as an interface, and that interface must inherit from react-native’s `TurboModule` interface. To run the JSI codegen, just run: ``` cd native yarn codegen-jsi ``` The input Flow schemas are located in `native/schema`. # Working with Phabricator -## Phabricator +## Setup -The last configuration step is to set up an account on Phabricator, where we handle code review. Start by [logging in to Phabricator](https://phab.comm.dev) using your GitHub account. +To set up an account on Phabricator, where we handle code review, start by [logging in to Phabricator](https://phab.comm.dev) using your GitHub account. Next, make sure you’re inside the directory containing the Comm Git repository, and run the following command: ``` arc install-certificate ``` This command will help you connect your Phabricator account with the local Arcanist instance, allowing you to run `arc diff` and `arc land` commands. ## Creating a new diff The biggest difference between GitHub PRs and Phabricator diffs is that a PR corresponds to a branch, whereas a diff corresponds to a commit. When you have a commit ready and want to submit it for code review, just run `arc diff` from within the Comm Git repo. `arc diff` will look at the most recent commit in `git log` and create a new diff for it. ## Updating a diff With GitHub PRs, updates are usually performed by adding on more commits. In contrast, in Phabricator a diff is updated by simply amending the existing commit and running `arc diff` again. When you run `arc diff`, it looks for a `Differential Revision: ` line in the commit text of the most recent commit. If Arcanist finds that line, it will assume you want to update the existing diff rather than create a new one. Other Arcanist commands such as `arc amend` (which amends commit text to match a diff on Phabricator) also look for the `Differential Revision: ` line. ## Working with a stack One of the advantages of Phabricator’s approach is that larger, multi-part changes can be split up into smaller pieces for review. These multi-part changes are usually referred to as a “stack” of diffs. When creating a diff that depends on another, you should make sure to create a dependency relationship between those two diffs, so that your reviewers can see the stack on Phabricator. The easiest way to do that is to include `Depends on D123` in the commit text of the child commit, but the dependency relationship can also be specified using the Phabricator web UI. You’ll find that mastering Git’s interactive rebase feature (`git rebase -i`) will help you a lot when working with stacks. Interactive rebases make it easy to “diff up” multiple commits at once, or to amend a specific commit in the middle of a stack in response to a review. ## Committing a diff After your diff has been accepted, you should be able to land it. To land a diff just run `arc land` from within the repository. If you have a stack of unlanded commits in your Git branch, `arc land` will attempt to land all of those diffs. If some of the diffs in your stack haven’t been accepted yet, you’ll need to create a new, separate branch that contains just the commits you want to land before running `arc land`. Note that you need commit rights to the repository in order to run `arc land`. If you don’t have commit rights, reach out to @ashoat for assistance. ## Final notes When developing, I usually just pop up three terminal windows, one for `yarn dev` in each of keyserver, web, and native. Note that it’s currently only possible to create a user account using the iOS or Android apps. The website supports logging in, but does not support account creation. Good luck, and let @ashoat know if you have any questions!