{"id":13453524,"url":"https://github.com/mherrmann/fbs-tutorial","last_synced_at":"2025-05-15T09:02:53.625Z","repository":{"id":38151034,"uuid":"114740664","full_name":"mherrmann/fbs-tutorial","owner":"mherrmann","description":"Tutorial for creating Python/Qt GUIs with fbs","archived":false,"fork":false,"pushed_at":"2021-09-16T14:22:05.000Z","size":838,"stargazers_count":2024,"open_issues_count":15,"forks_count":161,"subscribers_count":59,"default_branch":"master","last_synced_at":"2025-05-15T09:01:53.599Z","etag":null,"topics":["pyinstaller","pyqt5"],"latest_commit_sha":null,"homepage":"https://build-system.fman.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mherrmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-19T08:43:43.000Z","updated_at":"2025-05-07T14:41:02.000Z","dependencies_parsed_at":"2022-07-08T01:41:23.149Z","dependency_job_id":null,"html_url":"https://github.com/mherrmann/fbs-tutorial","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrmann%2Ffbs-tutorial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrmann%2Ffbs-tutorial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrmann%2Ffbs-tutorial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mherrmann%2Ffbs-tutorial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mherrmann","download_url":"https://codeload.github.com/mherrmann/fbs-tutorial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310513,"owners_count":22049468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pyinstaller","pyqt5"],"created_at":"2024-07-31T08:00:42.111Z","updated_at":"2025-05-15T09:02:53.539Z","avatar_url":"https://github.com/mherrmann.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# fbs tutorial\nThis tutorial shows how you can use [fbs](https://build-system.fman.io) to\ncreate a simple Python GUI and an associated installer:\n\n![Screenshot of sample app on Windows](files/screenshots/quote-app.png) ![Windows installer](files/screenshots/installer-windows.png) ![Screenshot of installer on Mac](files/screenshots/installer-mac.png)\n \nYou can follow this tutorial on Windows, Mac or Linux. You need Python 3.5 or\nlater.\n\n## Setup\nCreate a virtual environment in the current directory:\n\n    python3 -m venv venv\n\nActivate the virtual environment:\n\n    # On Mac/Linux:\n    source venv/bin/activate\n    # On Windows:\n    call venv\\scripts\\activate.bat\n\nThe remainder of the tutorial assumes that the virtual environment is active.\n\nInstall the required libraries (most notably, `fbs`):\n\n    pip install fbs-tutorial\n\n(If this produces errors, try `pip install wheel` first.)\n\nWe are using PyQt in this tutorial. In other fbs projects, you can use PySide\njust as well.\n\n## Start a project\nExecute the following command to start a new fbs project:\n\n    fbs startproject\n\nThe command creates a new folder called `src/` in your current directory.\nThis folder contains the minimum configuration for a bare-bones Python/Qt app.\n\n## Run the app\nTo run our little application from source, execute the following command:\n\n    fbs run\n\nThis shows an (admittedly not very exciting) window. Screenshots on\nWindows/Mac/Ubuntu:\n\n![Screenshot of sample app on Windows](files/screenshots/app-windows.png) ![Screenshot of sample app on Mac](files/screenshots/app-mac.png) ![Screenshot of sample app on Ubuntu](files/screenshots/app-ubuntu.png)\n\n## Source code of the sample app\nLet us now take a look at the source code that was generated by fbs. It is at\n[`src/main/python/main.py`](https://github.com/mherrmann/fbs/blob/master/fbs/builtin_commands/project_template/src/main/python/main.py):\n\n```python\nfrom fbs_runtime.application_context.PyQt5 import ApplicationContext\nfrom PyQt5.QtWidgets import QMainWindow\n\nimport sys\n\nif __name__ == '__main__':\n    appctxt = ApplicationContext()       # 1. Instantiate ApplicationContext\n    window = QMainWindow()\n    window.resize(250, 150)\n    window.show()\n    exit_code = appctxt.app.exec()      # 2. Invoke appctxt.app.exec()\n    sys.exit(exit_code)\n```\n\nThe important steps are highlighted as comments. They're the only boilerplate\nthat's required. In the middle of the code, you can see that a window is being\ncreated, resized and then shown.\n\n## Freezing the app\nWe want to turn the source code of our app into a standalone executable that can\nbe run on your users' computers. In the context of Python applications, this\nprocess is called \"freezing\".\n\nUse the following command to turn the app's source code into a standalone\nexecutable:\n\n    fbs freeze\n\nThis creates the folder `target/YourApp`. You can copy this directory to any\nother computer (with the same OS as yours) and run the app there! Isn't that\nawesome?\n\n## Creating an installer\nDesktop applications are normally distributed by means of an installer.\nOn Windows, this would be an executable called `YourAppSetup.exe`.\nOn Mac, mountable disk images such as `YourApp.dmg` are commonly used.\nOn Linux, `.deb` files are common on Ubuntu, `.rpm` on Fedora / CentOS, and\n`.pkg.tar.xz` on Arch.\n\nfbs lets you generate each of the above packages via the command:\n\n    fbs installer\n\nDepending on your operating system, this may require you to first install some\ntools. Please read on for OS-specific instructions.\n\n### Windows installer\nBefore you can use the `installer` command on Windows, please install\n[NSIS](http://nsis.sourceforge.net/Main_Page) and add its installation directory\nto your `PATH` environment variable.\n\nThe installer is created at `target/YourAppSetup.exe`. It lets your users pick\nthe installation directory and adds your app to the Start Menu. It also creates\nan entry in Windows' list of installed programs. Your users can use this to\nuninstall your app. The following screenshots show these steps in action:\n\n\u003cimg src=\"files/screenshots/installer-windows-1.png\" height=\"160\"\u003e \u003cimg src=\"files/screenshots/installer-windows-2.png\" height=\"160\"\u003e \u003cimg src=\"files/screenshots/installer-windows-3.png\" height=\"160\"\u003e \u003cimg src=\"files/screenshots/installer-windows-4.png\" height=\"160\"\u003e\n\n\u003cimg src=\"files/screenshots/uninstaller-windows-1.png\" height=\"160\"\u003e \u003cimg src=\"files/screenshots/uninstaller-windows-2.png\" height=\"160\"\u003e \u003cimg src=\"files/screenshots/uninstaller-windows-3.png\" height=\"160\"\u003e\n\n### Mac installer\nOn Mac, the `installer` command generates the file `target/YourApp.dmg`. When\nyour users open it, they see the following volume:\n\n![Screenshot of installer on Mac](files/screenshots/installer-mac.png)\n\nTo install your app, your users simply drag its icon to the _Applications_\nfolder (also shown in the volume).\n\n### Linux installer\nOn Linux, the `installer` command requires that you have\n[fpm](https://github.com/jordansissel/fpm). You can for instance follow\n[these instructions](https://fpm.readthedocs.io/en/latest/installation.html) to\ninstall it.\n\nDepending on your Linux distribution, fbs creates the installer at \n`target/YourApp.deb`, `...pkg.tar.xz` or `...rpm`. Your users can use these\nfiles to install your app with their respective package manager.\n\n## A more interesting example\nWe will now create a more powerful example. Here's what it looks like on\nWindows:\n\n![Quote app](files/screenshots/quote-app.png)\n\nWhen you click on the button in the window, a new quote is fetched from the\ninternet and displayed above.\n\nBefore you can run this example, you need to install the Python\n[requests](http://docs.python-requests.org/en/master/) library. To do this,\ntype in the following command:\n\n    pip install requests\n\nThe source code of the new app consists of two files:\n * [`main.py`](https://raw.githubusercontent.com/mherrmann/fbs-tutorial/master/files/main.py)\n * [`styles.qss`](https://raw.githubusercontent.com/mherrmann/fbs-tutorial/master/files/styles.qss)\n\nPlease copy the former over the existing file in `src/main/python/`, and the\nlatter into the _new_ directory `src/main/resources/base/`.\n\nOnce you have followed these steps, you can do `fbs run` (or `fbs freeze` etc.)\nas before.\n\nThe new app uses the following code to fetch quotes from the internet:\n\n```python\ndef _get_quote():\n    return requests.get('https://build-system.fman.io/quote').text\n```\n\nYou can see that it uses the `requests` library we just installed above. Feel \nfree to open\n[build-system.fman.io/quote](https://build-system.fman.io/quote) in the\nbrowser to get a feel for what it returns. Its data comes from a\n[public database](https://github.com/bmc/fortunes).\n\nThe app follows the same basic steps as before. It instantiates an application\ncontext and ends by calling `appctxt.app.exec_()`:\n\n```python\nappctxt = ApplicationContext()\n...\nexit_code = appctxt.app.exec_()\nsys.exit(exit_code)\n```\n\nWhat's different is what happens in between:\n\n```python\nstylesheet = appctxt.get_resource('styles.qss')\nappctxt.app.setStyleSheet(open(stylesheet).read())\nwindow = MainWindow()\nwindow.show()\n```\n\nThe first line uses\n[`get_resource(...)`](https://build-system.fman.io/manual/#get_resource) to\nobtain the path to [`styles.qss`](files/styles.qss). This is a QSS file, Qt's\nequivalent to CSS. The next line reads its contents and sets them as the\nstylesheet of the application context's `.app`.\n\nfbs ensures that `get_resource(...)` works both when running from source (i.e.\nduring `fbs run`) and when running the compiled form of your app. In the former\ncase, the returned path is in `src/main/resources`. In the latter, it will be in\nyour app's installation directory. fbs handles the corresponding details\ntransparently.\n\nThe next-to-last line instantiates `MainWindow`. This new class sets up the text\nfield for the quote and the button. When the button is clicked, it changes the\ncontents of the text field using `_get_quote()` above. You can find the\nfull code in [`main.py`](files/main.py).\n\nAs already mentioned, you can use `fbs run` to run the new app. But here's\nwhat's really cool: You can also do `fbs freeze` and `fbs installer` to\ndistribute it to other computers. fbs includes the `requests` dependency and the\n`styles.qss` file automatically.\n\n## Summary\nfbs lets you use Python and Qt to create desktop applications for Windows, Mac\nand Linux. It can create installers for your app, and automatically handles the\npackaging of third-party libraries and data files. These things normally take\nweeks to figure out. fbs gives them to you in minutes instead.\n\n## Where to go from here\nfbs's [Manual](https://build-system.fman.io/manual/) explains the technical\nfoundation of the steps in this tutorial. Read it to find out more about fbs's\nrequired directory structure, dependency management, handling of data files,\ncustom build commands, API and more.\n\nIf you have not used PyQt before: It's the library that allowed us in the above\nexamples to use Qt (a GUI framework) from Python. fbs's contribution is not to\ncombine Python and Qt. It's to make it very easy to package and deploy\nPython and Qt-based apps to your users' computers. For an introduction to PyQt,\nsee [here](https://build-system.fman.io/pyqt5-tutorial).\n\nFeel free to share the link to this tutorial!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmherrmann%2Ffbs-tutorial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmherrmann%2Ffbs-tutorial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmherrmann%2Ffbs-tutorial/lists"}