Builder Documentation Release 3.26.0 Christian Hergert, et al. Sep 13, 2017 Contents 1 Contents 3 1.1 Installation................................................3 1.1.1 via Flatpak...........................................3 1.1.1.1 Command Line....................................3 1.1.2 Local Flatpak Builds......................................4 1.1.3 via JHBuild...........................................4 1.1.3.1 Command Line....................................4 1.1.4 via Release Tarball.......................................5 1.1.5 Troubleshooting.........................................5 1.2 Exploring the Interface..........................................5 1.2.1 Project Greeter.........................................6 1.2.2 Workbench Window......................................6 1.2.3 Header Bar...........................................7 1.2.4 Switching Perspectives.....................................7 1.2.5 Showing and Hiding Panels...................................7 1.2.6 Build your Project........................................7 1.2.7 Editor..............................................9 1.2.8 Autocompletion......................................... 11 1.2.9 Documentation......................................... 11 1.2.10 Splitting Windows....................................... 12 1.2.11 Searching............................................ 14 1.2.12 Preferences........................................... 15 1.2.13 Command Bar.......................................... 16 1.2.14 Transfers............................................ 17 1.3 Projects.................................................. 18 1.3.1 Creating and Importing Projects................................ 18 1.3.1.1 Creating a new Project................................. 18 1.3.1.2 Cloning an Existing Project.............................. 20 1.3.2 Building your Project...................................... 20 1.3.3 Debugging your Project..................................... 21 1.3.4 Profiling your Project...................................... 23 1.3.5 Sharing your Project...................................... 25 1.4 Extensions................................................ 26 1.4.1 Enabling and Disabling Extensions............................... 26 1.4.2 Creating Your First Extension................................. 30 1.4.2.1 Loading our Extension................................ 30 i 1.4.2.2 Embedding Resources................................. 31 1.4.3 Extending the Workbench................................... 31 1.4.3.1 The Basics....................................... 31 1.4.3.2 Registering Workbench Actions............................ 32 1.4.3.3 Adding Widgets to the Header Bar.......................... 33 1.4.3.4 Registering Perspectives................................ 33 1.4.3.5 Adding Panels to the Workbench........................... 34 1.4.4 Extending the Greeter...................................... 35 1.4.4.1 Project Miners..................................... 35 1.4.4.2 Project Creation Workflows.............................. 36 1.4.5 Extending the Editor...................................... 37 1.4.5.1 Extending the Editor View.............................. 37 1.4.5.2 Managing Buffers................................... 38 1.4.5.3 Syntax Highlighting.................................. 38 1.4.5.4 Diagnostics and Fix-Its................................ 39 1.4.5.5 Autocompletion.................................... 39 1.4.5.6 Snippets........................................ 39 1.4.5.7 File Settings and Indentation............................. 39 1.4.6 Symbols and Semantic Analysis................................ 39 1.4.6.1 Go To Definition.................................... 39 1.4.6.2 Extending the Symbol Tree.............................. 39 1.4.6.3 Renaming Symbols.................................. 39 1.4.7 Extending the Build Pipeline.................................. 39 1.4.7.1 Implementing a Build System............................. 39 1.4.7.2 Extending the Build Pipeline............................. 41 1.4.8 Processes and Containers.................................... 43 1.4.8.1 Application Runtimes and Containers......................... 43 1.4.8.2 Subprocesses and Psuedo Terminals......................... 44 1.4.9 Extending the Device Manager................................. 46 1.4.10 Extending the Run Manager.................................. 47 1.4.11 Registering Keybindings.................................... 49 1.4.12 Integrating Language Servers.................................. 49 1.4.13 Extending Project Search.................................... 49 1.4.14 Extending Application Menus................................. 50 1.4.14.1 Extended Menu Features............................... 50 1.4.14.2 Accessing Merged Menus............................... 51 1.4.15 Registering Application Preferences.............................. 51 1.4.16 Creating and Performing Transfers............................... 53 1.4.17 Managing Worker Processes.................................. 54 1.4.18 Integrating Version Control................................... 54 1.5 How-To Guides.............................................. 54 1.5.1 Contents............................................. 54 1.5.1.1 Changing Indentation................................. 54 1.5.1.2 Search and Replace.................................. 55 1.5.1.3 Jump to Definition................................... 55 1.5.1.4 Searching for Symbols................................ 55 1.6 Troubleshooting............................................. 56 1.6.1 Verbose Output......................................... 56 1.6.2 Support Log........................................... 56 1.6.3 Counters............................................. 56 1.6.4 Test Builder Nightly...................................... 56 1.6.5 File a Bug............................................ 57 1.7 Contributing............................................... 57 1.7.1 Planning and Project Management............................... 57 ii 1.7.1.1 Responsibilities.................................... 57 1.7.2 Writing Documentation..................................... 57 1.7.2.1 Submitting Patches.................................. 58 1.7.2.2 Creating a Patch.................................... 58 1.7.2.3 Submitting a Patch................................... 58 1.7.2.4 GNOME git Best Practices.............................. 58 1.7.3 Contributing Code....................................... 58 1.7.3.1 Where to Contribute?................................. 58 1.7.4 IRC............................................... 59 1.7.5 File A Bug........................................... 59 1.7.6 Find A Bug To Work On.................................... 59 1.7.7 Building From Source..................................... 59 1.8 Credits.................................................. 60 iii iv Builder Documentation, Release 3.26.0 Welcome to the Builder project! We’re excited to have you here! The Builder project started out of a class teaching people to program for the GNOME platform. In the process, we realized that we need to improve our tooling so we started creating Builder! We hope you love using Builder to create great software for GNOME! Contents 1 Builder Documentation, Release 3.26.0 2 Contents CHAPTER 1 Contents Installation The preferred installation method for Builder is via Flatpak. This provides a bandwidth efficient and safe to use installation method that can be easily kept up to date. It is also the engine behind Builder’s powerful SDK! via Flatpak If you have a recent Linux distribution, such as Fedora 26, simply download the Stable Flatpak and click Install when Software opens. If Software does not automatically open, try opening the Stable flatpakref by double clicking it in your file browser. If you want to track Builder development, you might want the Nightly channel instead of Stable. Note: To build flatpak-based applications, ensure that the flatpak-builder program is installed. On Fedora, this is the flatpak-builder package. Command Line You can also use the command line to install Builder: Stable $ flatpak install --user --from https://git.gnome.org/browse/gnome-apps-nightly/plain/ ,!gnome-builder.flatpakref?h=stable $ flatpak run org.gnome.Builder Nightly 3 Builder Documentation, Release 3.26.0 $ flatpak install --user --from https://git.gnome.org/browse/gnome-apps-nightly/plain/ ,!gnome-builder.flatpakref $ flatpak run org.gnome.Builder Note: Nightly builds are built with tracing enabled. The tracing is fairly lightweight, but it includes a great deal of more debugging information. Local Flatpak Builds You can also build Builder as a flatpak yourself to test local changes. First, make a repo for your local builds: $ mkdir ~/my-flatpak-builds $ flatpak remote-add --user --no-gpg-verify my-flatpak-builds ~/my-flatpak-builds Now, in Builder’s source directory, use flatpak-builder to build a Builder flatpak and install it $ git clone https://git.gnome.org/browse/gnome-builder/ $ cd gnome-builder $ mkdir app $ flatpak-builder --ccache --repo=$HOME/my-flatpak-builds app org.gnome.Builder.json $ flatpak install --user my-flatpak-builds org.gnome.Builder Note: After following these steps once you can omit adding the remote or creating the app directory. You’ll also need to add the --force-clean option to flatpak-builder and use flatpak update rather than flatpak install. via JHBuild If you plan on contributing to the GNOME desktop and application suite, you may want to install Builder via JHBuild. See the Newcomers Tutorial for