CINXE.COM

<!doctype html> <html class="no-js" lang="en" data-content_root=""> <head><meta charset="utf-8"/> <meta name="viewport" content="width=device-width,initial-scale=1"/> <meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> <meta property="og:title" content="Building With Toolbx" /> <meta property="og:type" content="website" /> <meta property="og:url" content="https://handbook.gnome.org/development/toolbx.html" /> <meta property="og:site_name" content="GNOME Project Handbook" /> <meta property="og:description" content="This page provides a tutorial for those who want to build GNOME modules using Toolbx for the build environment. (For an overview of the build methods available for GNOME, see building.) The tutoria..." /> <meta property="og:image:width" content="1146" /> <meta property="og:image:height" content="600" /> <meta property="og:image" content="https://handbook.gnome.org/_images/social_previews/summary_development_toolbx_80018808.png" /> <meta property="og:image:alt" content="This page provides a tutorial for those who want to build GNOME modules using Toolbx for the build environment. (For an overview of the build methods availab..." /> <meta name="description" content="This page provides a tutorial for those who want to build GNOME modules using Toolbx for the build environment. (For an overview of the build methods available for GNOME, see building.) The tutoria..." /> <meta name="twitter:card" content="summary_large_image" /> <link rel="index" title="Index" href="../genindex.html" /><link rel="search" title="Search" href="../search.html" /><link rel="next" title="Legal" href="legal.html" /><link rel="prev" title="Building" href="building.html" /> <link rel="shortcut icon" href="../_static/handbook.ico"/> <title>Building With Toolbx - GNOME Project Handbook</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="../_static/styles/furo.css?digest=369552022d0b975c8e74270ce6eabe0fb7978f24" /> <link rel="stylesheet" type="text/css" href="../_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" /> <link rel="stylesheet" type="text/css" href="../_static/gnome.css" /> <style> body { --color-code-background: #f8f8f8; --color-code-foreground: black; --color-brand-primary: #4a86cf; --color-brand-content: #4a86cf; } @media not print { body[data-theme="dark"] { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } @media (prefers-color-scheme: dark) { body:not([data-theme="light"]) { --color-code-background: #202020; --color-code-foreground: #d0d0d0; } } } </style>  <script> var _paq = window._paq = window._paq || []; /* tracker methods like "setCustomDimension" should be called before "trackPageView" */ _paq.push(['trackPageView']); _paq.push(['enableLinkTracking']); (function() { var u="//webstats.gnome.org/"; _paq.push(['setTrackerUrl', u+'matomo.php']); _paq.push(['setSiteId', '46']); var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s); })(); </script>  </head> <body> <script> document.body.dataset.theme = localStorage.getItem("theme") || "auto"; </script> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-toc" viewBox="0 0 24 24"> <title>Contents</title> <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024"> <path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/> </svg> </symbol> <symbol id="svg-menu" viewBox="0 0 24 24"> <title>Menu</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu"> <line x1="3" y1="12" x2="21" y2="12"></line> <line x1="3" y1="6" x2="21" y2="6"></line> <line x1="3" y1="18" x2="21" y2="18"></line> </svg> </symbol> <symbol id="svg-arrow-right" viewBox="0 0 24 24"> <title>Expand</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right"> <polyline points="9 18 15 12 9 6"></polyline> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24"> <title>Light mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24"> <title>Dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon"> <path stroke="none" d="M0 0h24v24H0z" fill="none" /> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" /> </svg> </symbol> <symbol id="svg-sun-half" viewBox="0 0 24 24"> <title>Auto light/dark mode</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow"> <path stroke="none" d="M0 0h24v24H0z" fill="none"/> <circle cx="12" cy="12" r="9" /> <path d="M13 12h5" /> <path d="M13 15h4" /> <path d="M13 18h1" /> <path d="M13 9h4" /> <path d="M13 6h1" /> </svg> </symbol> </svg> <input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation"> <input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc"> <label class="overlay sidebar-overlay" for="__navigation"></label> <label class="overlay toc-overlay" for="__toc"></label> <div class="page"> <header class="mobile-header"> <div class="header-left"> <label class="nav-overlay-icon" for="__navigation"> <i class="icon"><svg><use href="#svg-menu"></use></svg></i> </label> </div> <div class="header-center"> <a href="../index.html"><div class="brand">GNOME Project Handbook</div></a> </div> <div class="header-right"> <div class="theme-toggle-container theme-toggle-header"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-header-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> </header> <aside class="sidebar-drawer"> <div class="sidebar-container"> <div class="sidebar-sticky"><a class="sidebar-brand" href="../index.html"> <span class="sidebar-brand-text">GNOME Project Handbook</span> </a><form class="sidebar-search-container" method="get" action="../search.html" role="search"> <input class="sidebar-search" placeholder="Search" name="q" aria-label="Search"> <input type="hidden" name="check_keywords" value="yes"> <input type="hidden" name="area" value="default"> </form> <div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree"> <ul class="current"> <li class="toctree-l1 has-children"><a class="reference internal" href="../get-in-touch.html">Get in Touch</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Get in Touch</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../get-in-touch/matrix.html">Matrix</a></li> <li class="toctree-l2"><a class="reference internal" href="../get-in-touch/discourse.html">Discourse</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../news.html">Project News</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Project News</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../news/planet-gnome.html">Planet GNOME</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../teams.html">Teams</a></li> <li class="toctree-l1"><a class="reference internal" href="../governance.html">Governance</a></li> <li class="toctree-l1 has-children"><a class="reference internal" href="../foundation.html">Foundation</a><input class="toctree-checkbox" id="toctree-checkbox-3" name="toctree-checkbox-3" role="switch" type="checkbox"/><label for="toctree-checkbox-3"><div class="visually-hidden">Toggle navigation of Foundation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2 has-children"><a class="reference internal" href="../foundation/board-of-directors.html">Board of Directors</a><input class="toctree-checkbox" id="toctree-checkbox-4" name="toctree-checkbox-4" role="switch" type="checkbox"/><label for="toctree-checkbox-4"><div class="visually-hidden">Toggle navigation of Board of Directors</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../foundation/board-of-directors/officers.html">Officers</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/board-of-directors/previous-boards.html">Previous Boards</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../foundation/committees.html">Committees</a><input class="toctree-checkbox" id="toctree-checkbox-5" name="toctree-checkbox-5" role="switch" type="checkbox"/><label for="toctree-checkbox-5"><div class="visually-hidden">Toggle navigation of Committees</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/circle.html">Circle Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/coc.html">Code of Conduct Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/compensation.html">Compensation Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/executive.html">Executive Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/finance.html">Finance Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/governance.html">Governance Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/governance.html#committee-charter">Committee Charter</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/internship.html">Internship Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/membership-and-elections.html">Membership & Elections Committee</a></li> <li class="toctree-l3"><a class="reference internal" href="../foundation/committees/travel.html">Travel Committee</a></li> </ul> </li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../infrastructure.html">Infrastructure</a><input class="toctree-checkbox" id="toctree-checkbox-6" name="toctree-checkbox-6" role="switch" type="checkbox"/><label for="toctree-checkbox-6"><div class="visually-hidden">Toggle navigation of Infrastructure</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../infrastructure/developer-access.html">Developer Access</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../infrastructure/accounts.html">Accounts</a><input class="toctree-checkbox" id="toctree-checkbox-7" name="toctree-checkbox-7" role="switch" type="checkbox"/><label for="toctree-checkbox-7"><div class="visually-hidden">Toggle navigation of Accounts</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../infrastructure/accounts/managing-accounts.html">Managing Accounts</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../infrastructure/email-aliases.html">Email Aliases</a></li> <li class="toctree-l2"><a class="reference internal" href="../infrastructure/blog-hosting.html">Blog Hosting</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../infrastructure/gitlab.html">GitLab</a><input class="toctree-checkbox" id="toctree-checkbox-8" name="toctree-checkbox-8" role="switch" type="checkbox"/><label for="toctree-checkbox-8"><div class="visually-hidden">Toggle navigation of GitLab</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../infrastructure/gitlab/hosting-requirements.html">Hosting Requirements</a></li> <li class="toctree-l3"><a class="reference internal" href="../infrastructure/gitlab/new-gnome-project.html">New GNOME Projects</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../infrastructure/ssh-keys.html">SSH Keys</a></li> <li class="toctree-l2"><a class="reference internal" href="../infrastructure/contact.html">Contact</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../release-planning.html">Release Planning</a><input class="toctree-checkbox" id="toctree-checkbox-9" name="toctree-checkbox-9" role="switch" type="checkbox"/><label for="toctree-checkbox-9"><div class="visually-hidden">Toggle navigation of Release Planning</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../release-planning/freezes.html">Freezes</a></li> <li class="toctree-l2"><a class="reference internal" href="../release-planning/release-team.html">Release Team</a></li> </ul> </li> <li class="toctree-l1 current has-children"><a class="reference internal" href="../development.html">Development</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-10" name="toctree-checkbox-10" role="switch" type="checkbox"/><label for="toctree-checkbox-10"><div class="visually-hidden">Toggle navigation of Development</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="change-submission.html">Change Submission</a></li> <li class="toctree-l2"><a class="reference internal" href="commit-messages.html">Commit Messages</a></li> <li class="toctree-l2"><a class="reference internal" href="building.html">Building</a></li> <li class="toctree-l2 current current-page"><a class="current reference internal" href="#">Building With Toolbx</a></li> <li class="toctree-l2"><a class="reference internal" href="legal.html">Legal</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../testing.html">Testing</a></li> <li class="toctree-l1 has-children"><a class="reference internal" href="../issues.html">Issue Tracking</a><input class="toctree-checkbox" id="toctree-checkbox-11" name="toctree-checkbox-11" role="switch" type="checkbox"/><label for="toctree-checkbox-11"><div class="visually-hidden">Toggle navigation of Issue Tracking</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../issues/reporting.html">Issue Reporting</a></li> <li class="toctree-l2"><a class="reference internal" href="../issues/stack-traces.html">Stack Traces</a></li> <li class="toctree-l2"><a class="reference internal" href="../issues/management.html">Issue Management</a></li> <li class="toctree-l2"><a class="reference internal" href="../issues/review.html">Issue Review</a></li> <li class="toctree-l2"><a class="reference internal" href="../issues/stock-responses.html">Stock Responses</a></li> <li class="toctree-l2"><a class="reference internal" href="../issues/template.html">New Issue Template</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../maintainers.html">Maintainers</a><input class="toctree-checkbox" id="toctree-checkbox-12" name="toctree-checkbox-12" role="switch" type="checkbox"/><label for="toctree-checkbox-12"><div class="visually-hidden">Toggle navigation of Maintainers</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../maintainers/making-a-release.html">Making a Release</a></li> <li class="toctree-l2"><a class="reference internal" href="../maintainers/branches.html">Branches</a></li> <li class="toctree-l2"><a class="reference internal" href="../maintainers/issue-management.html">Issue Management</a></li> </ul> </li> <li class="toctree-l1 has-children"><a class="reference internal" href="../events.html">Events</a><input class="toctree-checkbox" id="toctree-checkbox-13" name="toctree-checkbox-13" role="switch" type="checkbox"/><label for="toctree-checkbox-13"><div class="visually-hidden">Toggle navigation of Events</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l2"><a class="reference internal" href="../events/guadec.html">GUADEC</a></li> <li class="toctree-l2"><a class="reference internal" href="../events/gnome.asia.html">GNOME.Asia</a></li> <li class="toctree-l2 has-children"><a class="reference internal" href="../events/hackfests.html">Hackfests</a><input class="toctree-checkbox" id="toctree-checkbox-14" name="toctree-checkbox-14" role="switch" type="checkbox"/><label for="toctree-checkbox-14"><div class="visually-hidden">Toggle navigation of Hackfests</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../events/hackfests/organizing.html">Organize a Hackfest</a></li> <li class="toctree-l3"><a class="reference internal" href="../events/hackfests/template.html">Hackfest Template</a></li> </ul> </li> <li class="toctree-l2 has-children"><a class="reference internal" href="../events/travel.html">Travel</a><input class="toctree-checkbox" id="toctree-checkbox-15" name="toctree-checkbox-15" role="switch" type="checkbox"/><label for="toctree-checkbox-15"><div class="visually-hidden">Toggle navigation of Travel</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul> <li class="toctree-l3"><a class="reference internal" href="../events/travel/sponsorship-policy.html">Travel Sponsorship Policy</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </div> </aside> <div class="main"> <div class="content"> <div class="article-container"> <a href="#" class="back-to-top muted-link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"> <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path> </svg> <span>Back to top</span> </a> <div class="content-icon-container"> <div class="edit-this-page"> <a class="muted-link" href="https://gitlab.gnome.org/Teams/Websites/handbook.gnome.org/-/edit/main/source/development/toolbx.rst" title="Edit this page"> <svg aria-hidden="true" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" fill="none" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"/> <path d="M4 20h4l10.5 -10.5a1.5 1.5 0 0 0 -4 -4l-10.5 10.5v4" /> <line x1="13.5" y1="6.5" x2="17.5" y2="10.5" /> </svg> <span class="visually-hidden">Edit this page</span> </a> </div><div class="theme-toggle-container theme-toggle-content"> <button class="theme-toggle"> <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div> <svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg> </button> </div> <label class="toc-overlay-icon toc-content-icon" for="__toc"> <div class="visually-hidden">Toggle table of contents sidebar</div> <i class="icon"><svg><use href="#svg-toc"></use></svg></i> </label> </div> <article role="main" id="furo-main-content"> <section id="building-with-toolbx"> <h1>Building With Toolbx<a class="headerlink" href="#building-with-toolbx" title="Permalink to this heading">#</a></h1> <p>This page provides a tutorial for those who want to build GNOME modules using <a class="reference external" href="https://containertoolbx.org/">Toolbx</a> for the build environment. (For an overview of the build methods available for GNOME, see <a class="reference internal" href="building.html"><span class="doc">building</span></a>.)</p> <p>The tutorial below uses a Fedora-based Toolbx container, but most commands will work with other distros. It also assumes some preexisting familiarity with Git version control.</p> <section id="introduction-to-toolbx"> <h2>Introduction to Toolbx<a class="headerlink" href="#introduction-to-toolbx" title="Permalink to this heading">#</a></h2> <p>Each Toolbx container is a like a separate operating system which shares some things with your host operating system (like the files in your home directory) but whose software is kept separate, so you can install packages and manually build modules into it, without interfering with your host operating system.</p> <p>Toolbx containers are typically used through the terminal. Once created, you enter a Toolbx container in the terminal and from that point, most commands are carried out by the container rather than the host operating system.</p> <p>While “inside” a Toolbx container environment, you can access files from your home directory. However, other parts of the file system come from the container and are not shared with the host operating system.</p> <p>To use Toolbx, it needs to be installed on your system. If you are running Fedora Workstation or Fedora Silverblue, it is preinstalled. On other distributions you will need to manually install it.</p> </section> <section id="creating-a-toolbx-container"> <h2>Creating a Toolbx container<a class="headerlink" href="#creating-a-toolbx-container" title="Permalink to this heading">#</a></h2> <p>To create a container with Toolbx, run:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ toolbox create gnome </pre></div> </div> <p>Here, <code class="docutils literal notranslate"><span class="pre">gnome</span></code> is the name that will be gvien to the new container.</p> <p>By default, the container is based on the latest version of the host operating system. So, if you are using Fedora, then the new container will use the latest stable Fedora release. (If you want to specify the distro and version to be used, you can use the <code class="docutils literal notranslate"><span class="pre">--distro</span></code> and <code class="docutils literal notranslate"><span class="pre">--version</span></code> options.) When building GNOME modules, it is beneficial to use a distro that contains a recent GNOME version.</p> <p>If this is the first time a container has been created with Toolbx, it will download an image from which to create the container. This is a large file so may take a while. However, once the image has been downloaded, creating containers from it is quick.</p> <p>Once the Toolbx container has been created, enter it using:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ toolbox enter gnome </pre></div> </div> <p>You will see that the prompt is now preceded by an ⬢ symbol. This indicates that the prompt is inside a Toolbx container.</p> </section> <section id="building-modules"> <h2>Building modules<a class="headerlink" href="#building-modules" title="Permalink to this heading">#</a></h2> <p>Once you have a Toolbx container, you can build GNOME modules inside it. The following instructions for this are generic should work for most GNOME modules. However, you should check a module’s <code class="docutils literal notranslate"><span class="pre">README</span></code> file before trying to build it.</p> <p>First, create a directory in which to keep the source code of the modules that you want to build:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ mkdir checkout && cd checkout </pre></div> </div> <p>Then, use Git to clone the repository of the module you want to build. For example, to clone gnome-clocks you would run:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ git clone https://gitlab.gnome.org/GNOME/gnome-clocks.git </pre></div> </div> <p>Once the repository has been cloned, switch to it and install any required dependencies. For Fedora containers, an easy way to do this is using <code class="docutils literal notranslate"><span class="pre">dnf</span> <span class="pre">builddep</span></code>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ cd gnome-clocks ⬢ sudo dnf builddep -y gnome-clocks </pre></div> </div> <p>Now configure the build:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ meson setup builddir --prefix=/usr </pre></div> </div> <p>This means that the build will be cached in the directory called <code class="docutils literal notranslate"><span class="pre">builddir</span></code>, which is inside the project directory, and that the built version of the module will be put in the <code class="docutils literal notranslate"><span class="pre">/usr</span></code> directory.</p> <blockquote> <div><p><code class="docutils literal notranslate"><span class="pre">/usr</span></code> is inside the container and not the host operating system, so building and installing to this location will not affect your system. However, this is also the location where software is kept on the system, so building to this location will overwrite an existing version of the module you are building. This also means that using the container’s package manager to update or reinstall the module will overwrite the version that you have manually built. You are essentially replacing parts of the containers system software with the code you are building.</p> </div></blockquote> <p>Build the module:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ meson compile -C builddir </pre></div> </div> <p>Install the module:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ sudo meson install -C builddir </pre></div> </div> <p>Finally, stop any instances of the module which might already be running, and then run the newly installed version:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ killall gnome-clocks && gnome-clocks </pre></div> </div> </section> <section id="update-and-make-changes"> <h2>Update and make changes<a class="headerlink" href="#update-and-make-changes" title="Permalink to this heading">#</a></h2> <p>Assuming your build was successful, you can now make changes to the code, rebuild the module, and run it with your changes. To update the repository to get new changes, run:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ git pull -r </pre></div> </div> <p>To build the project with any changes, rerun:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ meson compile -C builddir </pre></div> </div> <p>To run the rebuilt project, rerun:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ killall gnome-clocks && gnome-clocks </pre></div> </div> </section> <section id="when-things-go-wrong"> <h2>When things go wrong<a class="headerlink" href="#when-things-go-wrong" title="Permalink to this heading">#</a></h2> <p>You may encounter issues when manually building GNOME modules. Typically these are easy to resolve and just require a bit of practice and detective work.</p> <section id="missing-dependencies"> <h3>Missing dependencies<a class="headerlink" href="#missing-dependencies" title="Permalink to this heading">#</a></h3> <p>Sometimes, dependencies required by a module may not be installed or may not be new enough. If this happens, the module will fail to build.</p> <p>If the build has failed, first check the build output in the terminal for error messages. There should be a message which indicates which module is missing or of the wrong version, which may look like <code class="docutils literal notranslate"><span class="pre">Config</span> <span class="pre">error:</span> <span class="pre">No</span> <span class="pre">package</span> <span class="pre">'foo-2.0'</span> <span class="pre">found</span></code>.</p> <p>Next, try to install the missing package using the package manager. This may require a bit of detective work to figure out which package is needed. You can try searching in your package manager for the missing module. In Fedora containers, you can also use dnf to install a particular pkg-config file that is missing. For example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>⬢ sudo dnf install 'pkgconfig(foo-2.0)' </pre></div> </div> <p>When installing dependencies, you will often need to install the version of the package, which is suffixed with <code class="docutils literal notranslate"><span class="pre">-devel</span></code> or <code class="docutils literal notranslate"><span class="pre">-dev</span></code>.</p> <p>If the required module isn’t available as a package, or the available package isn’t new enough, you will need to manually download and install it, using the manual build method described above.</p> <p>If you aren’t able to find the package or GNOME module that is missing, then you can <a class="reference internal" href="../get-in-touch/matrix.html"><span class="doc">ask for advice on Matrix</span></a>.</p> </section> <section id="changes-not-being-built"> <h3>Changes not being built<a class="headerlink" href="#changes-not-being-built" title="Permalink to this heading">#</a></h3> <p>If you have made changes to a module, and rebuilding doesn’t give you those changes, it could be due to a caching issue. To resolve this, try running <code class="docutils literal notranslate"><span class="pre">meson</span> <span class="pre">compile</span></code> with the <code class="docutils literal notranslate"><span class="pre">--clean</span></code> option. You can also delete the <code class="docutils literal notranslate"><span class="pre">builddir</span></code> directory from the project folder and then recompile the project.</p> </section> </section> </section> </article> </div> <footer> <div class="related-pages"> <a class="next-page" href="legal.html"> <div class="page-info"> <div class="context"> <span>Next</span> </div> <div class="title">Legal</div> </div> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> </a> <a class="prev-page" href="building.html"> <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg> <div class="page-info"> <div class="context"> <span>Previous</span> </div> <div class="title">Building</div> </div> </a> </div> </footer> </div> <aside class="toc-drawer"> <div class="toc-sticky toc-scroll"> <div class="toc-title-container"> <span class="toc-title"> On this page </span> </div> <div class="toc-tree-container"> <div class="toc-tree"> <ul> <li><a class="reference internal" href="#">Building With Toolbx</a><ul> <li><a class="reference internal" href="#introduction-to-toolbx">Introduction to Toolbx</a></li> <li><a class="reference internal" href="#creating-a-toolbx-container">Creating a Toolbx container</a></li> <li><a class="reference internal" href="#building-modules">Building modules</a></li> <li><a class="reference internal" href="#update-and-make-changes">Update and make changes</a></li> <li><a class="reference internal" href="#when-things-go-wrong">When things go wrong</a><ul> <li><a class="reference internal" href="#missing-dependencies">Missing dependencies</a></li> <li><a class="reference internal" href="#changes-not-being-built">Changes not being built</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </aside> </div> </div><script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> <script src="../_static/doctools.js"></script> <script src="../_static/sphinx_highlight.js"></script> <script src="../_static/scripts/furo.js"></script> </body> </html>