Become a Developer
If you like programming, and especially coding on FreeBSD, we would love to see you join the PC-BSD® Team as a PC-BSD® committer. Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the Bug database. If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started.. Once you have signed up, feel free to browse the active tickets in the PC-BSD®
Most of the PC-BSD® specific GUI tools are developed in C++ using the Qt Libraries, and other non-GUI development is done using standard Bourne shell scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list.
Getting the Source Code and Development Tools
The PC‑BSD® source code is available from github and git needs to be installed in order to download the source code. When using PC‑BSD®, git is included in the base install.
To download the source code, cd to the directory to store the source and type:
git clone git://github.com/pcbsd/pcbsd.git
This will create a directory named pcbsd/ which contains the local copy of the repository. To keep the local copy in sync with the official repository, run git pull within the pcbsd directory.
PC‑BSD® graphical applications use Qt version 4 and their source is located in pcbsd/src-qt4/. In order to compile the applications in this directory, install the "PC-BSD Build ToolChain" PBI using AppCafe®. To instead install this PBI from the command line, install the "devel/pcbsd-toolchain" PBI using pbi add.
Most of the PC‑BSD® source code is divided into two sub-categories:
- src-sh/ contains shell and C programs which do not include GUIs. These are the command line utilities used in TrueOS® and PC-BSD® and which are installed by the FreeBSD sysutils/pcbsd-utils port.
- src-qt4/ contains the Qt4-based GUIs seen in PC-BSD® and which are installed by the FreeBSD sysutils/pcbsd-utils-qt4 port
To compile the command line utilities:
cd src-sh make
To compile the graphical utilities:
cd src-qt4 qmake-qt4 make
Several Qt IDEs are available in AppCafe®. The "QtCreator" PBI is a full featured IDE designed to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. Qt Designer is lighter weight as it is only a .ui file editor and does not provide any other IDE functionality. It can be installed as the "qt4-designer" raw package using AppCafe® or pkg install.
If you plan to submit changes so that they can be included in PC-BSD®, fork the repository using the instructions at Fork a repo. Make your changes to the fork, then submit them by issuing a git pull request. Once your changes have been reviewed, they will be committed or sent back with suggestions.
Basic Guidelines for Writing a PC‑BSD® Utility
PC‑BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC‑BSD®. Going forward, we aim to present a unified design so that programs feel "familiar" to users. As an example, while programs could have "File", "Main", or "System" as their first entry on the "File menu", we want to present one option, "File", as it is the accepted norm for the first category on the menu bar.
This section describes a small list of guidelines to menu and program design in PC‑BSD®. Since most programs designed for the last couple of decades have followed this structure, it makes sense for us to follow the same standard.
Any graphical program that is a full-featured utility, such as Warden® or AppCafe®, should have a file menu. However, file menus are not necessary for small widget programs or dialogue boxes. When making a file menu, a good rule of thumb is keep it simple. Most PC‑BSD® utilities do not need more than two or three items on the file menu. An example of a well laid out "File" menu is AppCafe®, shown in Figure 11.3a.
"Configure" is our adopted standard for the category that contains "Settings" or other configuration related settings. If additional categories are needed, check to see what other PC‑BSD® utilities are using.
File Menu Icons
File menu icons are taken from the KDE "Oxygen" theme located in /usr/local/share/icons/oxygen. Use these file menu icons so we do not have a bunch of different icons used for the same function. Table 11.3a lists the commonly used icons and their default file names.
Table 11.3a: Commonly Used File Menu Icons
|Function||File Menu Icon||File Name|
|Quit||row 1, cell 2||window-close.png|
|Settings||row 2, cell 2||configure.png|
PC‑BSD® utilities use these buttons as follows:
- Apply: applies settings and leaves the window open.
- Close: closes program without applying settings.
- OK: closes dialogue window and saves settings.
- Cancel: closes dialogue window without applying settings.
- Save: saves settings and closes window.
Fully functional programs like AppCafe® and Warden® do not use close buttons on the front of the application. Basically, whenever there is a "File" menu, that and an x in the top right corner of the application are used instead. Dialogues and widget programs are exceptions to this rule. A good example of a widget program would be Update Manager.
Many users benefit from keyboard shortcuts and we aim to make them available in every PC‑BSD® utility. Qt makes it easy to assign keyboard shortcuts. For instance, to configure keyboard shortcuts that browse the "File" menu, put &File in the text slot for the menu entry when making the application. Whichever letter has the & symbol in front of it will become the hot key. You can also make a shortcut key by clicking the menu or submenu entry and assigning a shortcut key. Be careful not to duplicate hot keys or shortcut keys. Every key in a menu and submenu should have a key assigned for ease of use and accessibility. Tables 11.3b and 11.3c summarize the commonly used shortcut and hot keys.
Table 11.3b: Shortcut Keys
|CTRL + Q||Quit|
Table 11.3c: Hot Keys
|Alt + Q||Quit|
|Alt + S||Settings|
|Alt + I||Import|
|Alt + E||Export|
|ALT + F||File Menu|
|ALT + C||Configure Menu|
|ALT + H||Help Menu|
Saving Settings in a Qt Application
When saving an application's settings, the QSettings class should be used if possible. There are two different "organizations", depending on whether the application is running with root permissions or user permissions. Use "PCBSD" for the organization for applications that run with user permissions and "PCBSD-root" for applications that are started with root permissions via sudo. Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. Examples 11.3a and 11.3b demonstrate how to use the QSettings class for each type of permission.
Example 11.3a: User Permission Settings
Example 11.3b: Root Permission Settings
Developers will also find the following resources helpful: