1.. _module-pw_ide-design-projects: 2 3======== 4Projects 5======== 6.. pigweed-module-subpage:: 7 :name: pw_ide 8 9There are broadly two types of Pigweed projects that Pigweed's IDE tooling 10supports: 11 12* Bootstrap projects, in which a development environment is populated by 13 sourcing binary dependencies from CIPD, and is accessed by setting environment 14 variables via ``bootstrap`` and ``activate`` shell scripts. Usually, the build 15 system is GN or CMake. 16 17* Bazel projects, in which Bazel is the build system, Bazel manages development 18 environment dependencies, and the ``bazel`` (or ``bazelisk``) command is the 19 entry point into all tooling 20 21Other project configurations are possible, but these are the two that our IDE 22tooling recognizes and supports. 23 24.. _module-pw_ide-design-projects-project-root: 25 26----------------- 27Project structure 28----------------- 29For both project types, we look for the presence of a ``pigweed.json`` file to 30indicate the root of the project directory. 31 32.. _module-pw_ide-design-projects-bootstrap: 33 34Bootstrap projects 35================== 36This project structure has the following properties: 37 38* Development tools and dependences are located in an ``environment`` directory. 39 40.. note:: 41 42 The location and name of the ``environment`` can be actually customized when 43 running ``bootstrap.sh``, and multiple independent environments are 44 supported. 45 46* Access to the development environment is provided through mutations to the 47 shell environment; the ``$PATH`` is modified to point to locations in 48 ``environment``, and Pigweed-specific environment variables are used to 49 configure the development environment. 50 51* A ``bootstrap.sh`` script creates the ``environment`` directory, populates it 52 with development tools and dependencies, and modifies the environment of the 53 shell in which the script was run to provide access to the development 54 environment. 55 56* As a side effect of the bootstrap process, an ``actions.json`` file is created 57 in the ``environment`` directory that describes the mutations to the shell 58 environment required to provide access to the development environment. 59 60* Pigweed commands are made available via an executable called ``pw``. 61 62Assuming the environment has already been bootstrapped, exposing the development 63environment to an IDE or other developer tooling requires: 64 65* Finding the ``environment`` directory, or potentially multiple ``environment`` 66 directories. We do this by looking for directories with an ``actions.json`` 67 file. 68 69* Executing commands within a shell environment modified per the 70 ``actions.json`` file. How this is done depends on the language and runtime 71 of the IDE. An example in JavaScript: 72 73.. code-block:: js 74 75 // Assuming `actionsJson` is a parsed `actions.json` file, and `activateEnv` 76 // is a function that applies the mutations described in `actionsJson` to 77 // a shell environment. 78 const activatedEnv = activateEnv(process.env, actionsJson); 79 child_process.exec("clang", activatedEnv); 80 81If the environment has not been bootstrapped yet, we just need to run 82``bootstrap.sh``. It's not necessary to capture the mutated shell environment 83that results from running the script, since we have access to it through the 84steps described above. 85 86.. _module-pw_ide-design-projects-bazel: 87 88Bazel projects 89============== 90This project structure has the following properties: 91 92* Development tools and dependences are managed by Bazel. There are multiple 93 mechanisms for this, including 94 `WORKSPACE <https://bazel.build/concepts/build-ref#workspace>`_ and 95 `bzlmod <https://docs.bazel.build/versions/5.1.0/bzlmod.html>`_. Regardless of 96 the mechanism used, Bazel manages the tools and dependencies, and their 97 location on disk. 98 99* The Bazel environment is created and updated by running a Bazel build command. 100 101* Access to tools and commands in the development environment is provided by 102 Bazel itself. In other words, the ``bazel`` executable is the entry point to 103 all project operations. 104 105So all that's required to expose the development environment to an IDE is to 106execute ``bazel run`` commands. 107 108Managing Bazel environments 109--------------------------- 110It's important to use the version of Bazel specified by the project, and to use 111a single Bazel environment and build directory regardless of the tools the 112developer is using. For example, a developer should be able to edit code in 113their IDE and run Bazel commands from a separate terminal and be sure that all 114of those actions will execute within the same environment. 115 116We ensure that behavior by using ``bazelisk`` instead of plain ``bazel``. 117It wraps ``bazel`` and ensures that your project uses the exact version of Bazel 118specified in the project's ``.bazelversion`` file. 119 120A developer can have multiple installations of ``bazelisk`` from different 121sources, and invocations of any of those executables on the same project will 122all run in the same Bazel environment. So we can actually bundle ``bazelisk`` 123with the IDE, ensuring that it's available to IDE functionality, without 124worrying about it conflicting with the developer's use of ``bazelisk`` in the 125terminal or in other tools. 126