AppCafe® provides an intuitive, graphical method for installing and managing PBIs and packages. AppCafe® does not require the root password to install software. This means that you do not have to give out the root password on multi-user systems. However, it will prompt for the user's password and will fail if that user is not a member of the ''wheel'' group. This allows you to control which users are able to manage software.

+

AppCafe® provides an intuitive, graphical method for installing, managing, and upgrading PBIs and packages. AppCafe® does not require the root password to install software. This means that you do not have to give out the root password on multi-user systems. However, it will prompt for the user's password and will fail if that user is not a member of the ''wheel'' group. This allows you to control which users are able to manage software.

<!--T:5-->

<!--T:5-->

−

If you prefer to manage PBIs from the command line, see the section on using the {{local|link=PBI Manager}} suite of command line utilities. Refer to {{local|link=AppCafe®/10.1#Using_the_CLI_pkg_Utilities|txt=Using the CLI '''pkg''' Utilities}} for instructions on managing packages from the command line.

+

If you prefer to manage PBIs from the command line, see the section on using the {{local|link=PBI Manager}} suite of command line utilities. Refer to [[AppCafe®/10.1#Using_the_CLI_pkg_Utilities|Using the CLI '''pkg''' Utilities]] for instructions on managing packages from the command line.

=== Finding and Installing and Software === <!--T:7-->

=== Finding and Installing and Software === <!--T:7-->

Line 15:

Line 15:

To manage software, start AppCafe® by double-clicking its icon on the Desktop, going to {{traverse|Control Panel|AppCafe®|here=AppCafe®}}, or by typing '''pc-su pc-softwaremanager''' from a command prompt. When prompted, input your password. As seen in Figure 7.1a, AppCafe® will open into the “Browse for Apps” tab.

To manage software, start AppCafe® by double-clicking its icon on the Desktop, going to {{traverse|Control Panel|AppCafe®|here=AppCafe®}}, or by typing '''pc-su pc-softwaremanager''' from a command prompt. When prompted, input your password. As seen in Figure 7.1a, AppCafe® will open into the “Browse for Apps” tab.

−

In the example shown in Figure 7.1a, 1,372 PBIs and 23,297 packages are currently available. This tab provides several buttons and panes:

+

<!--T:75-->

+

In the example shown in Figure 7.1a, 2,172 PBIs and 23,343 packages are currently available. This tab provides several buttons and panes:

* '''Back button:''' click the drop-down menu to return to a previous search or category.

+

+

<!--T:144-->

* '''Home button:''' click this button to return back to this initial screen.

* '''Home button:''' click this button to return back to this initial screen.

+

<!--T:77-->

* '''Browse Categories button:''' click this button to access a list of software categories. Click on the name of a software category to browse for its available software.

* '''Browse Categories button:''' click this button to access a list of software categories. Click on the name of a software category to browse for its available software.

+

<!--T:78-->

* '''Search bar/button:''' if you know the name of the application you would like to install, type its name into the “Search Here” bar and either press enter or click the search (binoculars) button.

* '''Search bar/button:''' if you know the name of the application you would like to install, type its name into the “Search Here” bar and either press enter or click the search (binoculars) button.

+

<!--T:79-->

* '''Application Spotlight pane:''' software the PC-BSD® team recommends as being notable for their software category.

* '''Application Spotlight pane:''' software the PC-BSD® team recommends as being notable for their software category.

+

<!--T:80-->

* '''PC-BSD Recommendations pane:''' a list of essential applications for new users.

* '''PC-BSD Recommendations pane:''' a list of essential applications for new users.

+

<!--T:81-->

* '''New pane:''' software which has been recently added to the AppCafe®.

* '''New pane:''' software which has been recently added to the AppCafe®.

<!--T:43-->

<!--T:43-->

In the example shown in Figure 7.1b, the user searched for the “gimp” application, then clicked the search result.

In the example shown in Figure 7.1b, the user searched for the “gimp” application, then clicked the search result.

−

[[File:Appcafe3h.png|thumb|393px|'''Figure 7.1b: Browsing the Information Available for a PBI''']]

+

[[File:Appcafe3j.png|thumb|393px|'''Figure 7.1b: Browsing the Information Available for a PBI''']]

+

[[File:Installed2b.png|thumb|393px|'''Figure 7.1c: Viewing the Information for an Installed Application''']]

<!--T:10-->

<!--T:10-->

−

The following information is available for each application. Note that the rating and tips information is interactive, allowing users to share their tips with other PC-BSD® users. In order to do so, first create a wiki account at the {{citelink|url=wiki.pcbsd.orgtxt=PC-BSD® wiki}}, click on the activation email for the account, and login.

+

The following information is available for each application. Note that the rating and tips information is interactive, allowing users to share their tips with other PC-BSD® users. In order to do so, first create a wiki account at the {{citelink|url=http://wiki.pcbsd.org|txt=PC-BSD® wiki}}, click on the activation email for the account, and login.

+

<!--T:11-->

<!--T:11-->

* The software category for the application. In this case, “Gimp” is in the “Graphics” category.

* The software category for the application. In this case, “Gimp” is in the “Graphics” category.

+

<!--T:82-->

* Name and icon of the application.

* Name and icon of the application.

Line 44:

Line 58:

* A hyperlink to the application's website. In this example, clicking "GIMP Team" will open gimp.org in the user's default web browser.

* A hyperlink to the application's website. In this example, clicking "GIMP Team" will open gimp.org in the user's default web browser.

−

* A rating of up to five stars. Click the stars to open the PC-BSD® wiki page for the application. If you login to the wiki and hover the mouse over the number of stars to select, it will add your ranking and increment the vote number. If you make a mistake in your vote, simply click the “remove” button and re-select the desired number of stars.

+

<!--T:83-->

+

* A rating of up to five stars. Click the stars to open the PC-BSD® wiki page for the application. If you login to the wiki and hover the mouse over the number of stars to select, it will add your ranking and increment the vote number. If you make a mistake in your vote, refresh the browser, click the “remove” button, and re-select the desired number of stars.

+

<!--T:84-->

* A “User Tips” link. Click the link to open the PC-BSD® wiki page for the application. If you login to the wiki, you can add your own usage tips for the application.

* A “User Tips” link. Click the link to open the PC-BSD® wiki page for the application. If you login to the wiki, you can add your own usage tips for the application.

Line 58:

Line 74:

<!--T:15-->

<!--T:15-->

−

* The platform (i386 for 32-bit applications and amd64 for 64-bit applications). If the application only provides a 32-bit version, AppCafe® will install the 32-bit application and PC-BSD® will still be able to run the program.

+

* The application's version and platform (32-bit or 64-bit). If the application only provides a 32-bit version, AppCafe® will install the 32-bit application and PC-BSD® will still be able to run the program.

<!--T:45-->

<!--T:45-->

Line 69:

Line 85:

The following tabs are also available. If a tab is greyed out, it means that that information is not currently available for this particular application.

The following tabs are also available. If a tab is greyed out, it means that that information is not currently available for this particular application.

+

<!--T:85-->

* '''Description:''' of the software.

* '''Description:''' of the software.

+

<!--T:86-->

* '''Screenshots:''' click the “View Full Size” button under the screenshot to view the full screen version of the screenshot.

* '''Screenshots:''' click the “View Full Size” button under the screenshot to view the full screen version of the screenshot.

+

<!--T:87-->

* '''Plugins:''' provides an installable list of associated plugins. For an example, search for “firefox” and open its “Plugins” tab.

* '''Plugins:''' provides an installable list of associated plugins. For an example, search for “firefox” and open its “Plugins” tab.

+

<!--T:88-->

* '''Similar:''' provides an installable list of applications that provide similar functionality.

* '''Similar:''' provides an installable list of applications that provide similar functionality.

+

<!--T:89-->

* '''Build Options:''' shows the values of the make options that the PBI or package was built with.

* '''Build Options:''' shows the values of the make options that the PBI or package was built with.

+

+

<!--T:145-->

+

[[File:Appcafe41.png|left|thumb|393px|'''Figure 7.1d: Viewing the List of Installed Software in AppCafe®''']]

<!--T:21-->

<!--T:21-->

Once you find a PBI that you would like to install, click on its “Install Now!” icon. A yellow status bar at the bottom of the screen will show the download and installation status. Once the installation is complete, some of the contents of this screen will change, as seen in the example in Figure 7.1c.

Once you find a PBI that you would like to install, click on its “Install Now!” icon. A yellow status bar at the bottom of the screen will show the download and installation status. Once the installation is complete, some of the contents of this screen will change, as seen in the example in Figure 7.1c.

The “Install Now!” button will change to “Installed” and the following buttons are now available:

The “Install Now!” button will change to “Installed” and the following buttons are now available:

+

<!--T:92-->

* '''Launch:''' provides a drop-down menu for starting the application from its available start modes. Some applications start in graphical mode, some in command-line mode, and some offer both modes.

* '''Launch:''' provides a drop-down menu for starting the application from its available start modes. Some applications start in graphical mode, some in command-line mode, and some offer both modes.

−

* '''Contact Maintainer:''' if this button is clicked, a pop-up message offers to launch the default email client, if one has been configured. It also indicates the email address of the FreeBSD port maintainer for that application in case one prefers to manually open their email client. If a default email client is configured, it will automatically fill in this email address so that you can send feedback to the maintainer. Typically, this is done to send an error report or a patch to the maintainer.

+

<!--T:93-->

+

* '''Contact Maintainer:''' if this button is clicked, a pop-up message offers to launch the default email client, if one has been configured. It also indicates the email address of the FreeBSD port maintainer for that application in case one prefers to manually open their email client. If a default email client is configured, it will automatically fill in this email address as well as the important information regarding the PBI such as the build date, architecture, FreeBSD version, and version number. This allows you to send an error report or a patch to the maintainer.

+

<!--T:94-->

* '''Shortcuts:''' click this button to add or remove a desktop shortcut to the application.

* '''Shortcuts:''' click this button to add or remove a desktop shortcut to the application.

−

=== Managing Installed Software ===

+

=== Managing Installed Software === <!--T:95-->

+

<!--T:96-->

To manage software that is currently installed, use the “Installed” tab. Figure 7.1d shows a screenshot of this tab after “gimp” is successfully installed.

To manage software that is currently installed, use the “Installed” tab. Figure 7.1d shows a screenshot of this tab after “gimp” is successfully installed.

The list of installed applications can be sorted by “Program name”, “Version”, “Status” (of any running/pending “Actions”), “Size”, “Installed” (date of installation), and “Architecture”. Click the name of the desired column to change the sorting.

The list of installed applications can be sorted by “Program name”, “Version”, “Status” (of any running/pending “Actions”), “Size”, “Installed” (date of installation), and “Architecture”. Click the name of the desired column to change the sorting.

+

<!--T:97-->

If you check the box for at least one installed application and click the “Actions” button, the following actions become available:

If you check the box for at least one installed application and click the “Actions” button, the following actions become available:

+

<!--T:98-->

* '''Desktop Icons:''' used to add or remove a shortcut to the application on any installed desktop that supports icons.

* '''Desktop Icons:''' used to add or remove a shortcut to the application on any installed desktop that supports icons.

+

<!--T:99-->

* '''Version Lock:''' used to “Lock Current Version” so that it will not be updated until “Unlock Application” is selected. An application that is locked will have a lock icon next to its “Version”. Locking an application can be appropriate if there is a known issue in a more recent version of the application.

* '''Version Lock:''' used to “Lock Current Version” so that it will not be updated until “Unlock Application” is selected. An application that is locked will have a lock icon next to its “Version”. Locking an application can be appropriate if there is a known issue in a more recent version of the application.

+

<!--T:100-->

* '''Uninstall:''' will uninstall the checked applications. Once the removal is complete, that software will be removed from the “Installed” list.

* '''Uninstall:''' will uninstall the checked applications. Once the removal is complete, that software will be removed from the “Installed” list.

+

<!--T:101-->

* '''Cancel Actions:''' cancels any currently pending or running operations such as uninstallation, updating, or installation.

* '''Cancel Actions:''' cancels any currently pending or running operations such as uninstallation, updating, or installation.

Line 122:

Line 153:

<!--T:33-->

<!--T:33-->

−

Click the “Show Details” button to view the list of outdated software. The listing will show the current version as well as the newer version for the software as well as any affected dependencies and will end with the size for the amount of new software to be downloaded.Click “Yes” to start the upgrade or “No” to cancel the upgrade request.

+

In this example, the “Show Details” button was clicked in order to view the list of outdated software. The listing will show the current version as well as the newer version for the software as well as any affected dependencies and will end with the size for the amount of new software to be downloaded. Click “Yes” to start the upgrade or “No” to cancel the upgrade request.

−

Once the upgrade is started, a status bar will indicate the progress of the download and upgrade process in an “Overview” tab. To see more detailed messages, click the “Update Details” tab. The upgrade process will save all of the current version's settings. For example, when Firefox is upgraded, it will keep all of your bookmarks, history, and cache.

+

<!--T:102-->

+

As seen in Figure 7.1f, pnce the upgrade is started, a status bar will indicate the progress of the download and upgrade process in an “Overview” tab. To see more detailed messages, click the “Update Details” tab. The upgrade process will save all of the current version's settings. For example, when Firefox is upgraded, it will keep all of your bookmarks, history, and cache.

This screen will indicate when the upgrade is finished and will offer to reboot the system if the upgrade requires a reboot. If a reboot is needed and you cancel it, finish saving your work then reboot the system manually.

This screen will indicate when the upgrade is finished and will offer to reboot the system if the upgrade requires a reboot. If a reboot is needed and you cancel it, finish saving your work then reboot the system manually.

Line 135:

Line 169:

The “File” menu provides the following options:

The “File” menu provides the following options:

+

<!--T:105-->

* '''Vulnerability Info:''' if you click this menu option, the FreshPorts VuXML page will open in the default web browser. This contains a list of all known vulnerabilities to software which has been ported to FreeBSD, and is thus available for installation in PC-BSD®. By default, the most recent vulnerabilities are shown first. There is a link on that web page to order the list of vulnerabilities by package name.

* '''Vulnerability Info:''' if you click this menu option, the FreshPorts VuXML page will open in the default web browser. This contains a list of all known vulnerabilities to software which has been ported to FreeBSD, and is thus available for installation in PC-BSD®. By default, the most recent vulnerabilities are shown first. There is a link on that web page to order the list of vulnerabilities by package name.

+

<!--T:106-->

* '''Import PBI List:''' if you click this option, it will ask you to browse to the location of an existing PBI list, an ASCII text file ending with a .pbilist extension that contains the names of PBIs (without a version number), one per line. An example is seen in Example 7.1a. If you import a PBI list into AppCafe®, it will add those applications to the installation queue so that they can be installed. AppCafe® will ignore any invalid lines and PBIs which are already installed.

* '''Import PBI List:''' if you click this option, it will ask you to browse to the location of an existing PBI list, an ASCII text file ending with a .pbilist extension that contains the names of PBIs (without a version number), one per line. An example is seen in Example 7.1a. If you import a PBI list into AppCafe®, it will add those applications to the installation queue so that they can be installed. AppCafe® will ignore any invalid lines and PBIs which are already installed.

+

+

<!--T:107-->

* '''Export PBI List:''' if you click this option on a system that already has PBIs installed, you can then import that list into another PC-BSD® system. By default, the exported list will be saved as exportfile.pbilist.

* '''Export PBI List:''' if you click this option on a system that already has PBIs installed, you can then import that list into another PC-BSD® system. By default, the exported list will be saved as exportfile.pbilist.

+

<!--T:108-->

* '''Quit:''' click this option to close AppCafe®.

* '''Quit:''' click this option to close AppCafe®.

+

<!--T:109-->

'''Example 7.1a: Sample PBI List'''

'''Example 7.1a: Sample PBI List'''

{{txtbox|box=apacheopenoffice{{nbsp|64}}

{{txtbox|box=apacheopenoffice{{nbsp|64}}

Line 160:

Line 200:

The "Configure" menu contains the following options:

The "Configure" menu contains the following options:

+

<!--T:110-->

* '''Repository Settings:''' as seen in Figure 7.1g, this option is used to select the package set. "Production" is the default and recommended setting for most users. Software updates are provided every three months, which gives sufficient time for new software versions to be tested. "Edge" is meant for users who wish to assist with software testing or who can tolerate the occasional breakage caused by installing new software versions. Software updates are provided approximately every two weeks. "Custom" is for administrators who have {{local|link=Create_Your_Own_PBI_Repository|created their own PBI repository}}; click the “+” button to browse to the location of the custom ''.rpo'' file. To allow switching between custom repositories, multiple custom repositories can be listed, but only the one marked as active will be used.

* '''Repository Settings:''' as seen in Figure 7.1g, this option is used to select the package set. "Production" is the default and recommended setting for most users. Software updates are provided every three months, which gives sufficient time for new software versions to be tested. "Edge" is meant for users who wish to assist with software testing or who can tolerate the occasional breakage caused by installing new software versions. Software updates are provided approximately every two weeks. "Custom" is for administrators who have {{local|link=Create_Your_Own_PBI_Repository|created their own PBI repository}}; click the “+” button to browse to the location of the custom ''.rpo'' file. To allow switching between custom repositories, multiple custom repositories can be listed, but only the one marked as active will be used.

+

<!--T:111-->

* '''Refresh PBI Index:''' click this option to get the latest copy of the list of available PBIs and packages. Otherwise, this list is automatically refreshed each time AppCafe® is started.

* '''Refresh PBI Index:''' click this option to get the latest copy of the list of available PBIs and packages. Otherwise, this list is automatically refreshed each time AppCafe® is started.

+

<!--T:112-->

* '''Developer Mode:''' check this box to add a pane of debugging messages to the bottom of AppCafe®. This can be useful to help determine the problem if there is an error in installing or upgrading software.

* '''Developer Mode:''' check this box to add a pane of debugging messages to the bottom of AppCafe®. This can be useful to help determine the problem if there is an error in installing or upgrading software.

The default AppCafe® view only provides information about PBIs but does not provide information about packages. This means that the “Installed” tab will only show installed PBIs and the “Browse for Apps” tab and search function will only display available PBIs. This default can be changed using the options in the “Install View” menu, which changes the appearance of the "Install" tab, and “Browser View” menu, which changes the appearance of the "Browse for Apps" tab.

The default AppCafe® view only provides information about PBIs but does not provide information about packages. This means that the “Installed” tab will only show installed PBIs and the “Browse for Apps” tab and search function will only display available PBIs. This default can be changed using the options in the “Install View” menu, which changes the appearance of the "Install" tab, and “Browser View” menu, which changes the appearance of the "Browse for Apps" tab.

+

<!--T:115-->

The “Install View” menu contains the following options:

The “Install View” menu contains the following options:

−

* '''Show Orphan Packages:''' when this box is checked, the contents of the “Installed” tab change to the list of installed software which are not dependencies of any other installed application. An example is shown in Figure 7.1h. The list will either be PBIs or PBIs and packages, depending upon whether or not “Show Raw Packages” is also checked.

+

<!--T:116-->

+

* '''Show Raw Packages:''' when this box is checked, it adds the list of installed packages to the list of installed PBIs. An example is seen in Figure 7.1h.

−

* '''Show Raw Packages:''' when this box is checked, it adds the list of installed packages to the list of installed PBIs.

+

<!--T:142-->

+

* '''Show Orphan Packages:''' when this box is checked, the contents of the “Installed” tab change to the list of installed software which are not dependencies of any other installed application. An example is shown in Figure 7.1i. The list will either be PBIs or PBIs and packages, depending upon whether or not “Show Raw Packages” is also checked.

−

* '''Show Base Packages:''' when this box is checked, the contents of the “Installed” tab change to the list of installed base system packages, or the packages which get installed with the operating system. If “Show Raw Packages” is also checked, the listing will include every installed package rather than just the name of the system component.

+

<!--T:118-->

+

* '''Show Base Packages:''' when this box is checked, the contents of the “Installed” tab change to the list of installed base system packages, or the packages which get installed with the operating system. If “Show Raw Packages” is also checked, the listing will include every installed package rather than just the name of the system component. An example is seen in Figure 7.1j.

−

The next two options will be greyed out unless at least one jail [[Warden®/10.1|has been created]] and is running.

* '''Show Local System:''' is used to toggle the “Installed” tab between that of the host system and a running jail. This box remains checked unless a jail is selected in “Show Jail”. Recheck this box to change the view back from the selected jail to the host system.

+

<!--T:119-->

+

By default, AppCafe® displays software information for the computer running PC-BSD®. It can also be used to manage the software running in a jail, as long as at least one jail [[Warden®/10.1|has been created]] and is running. To manage a jail, click the “Jail” button and select the name of the jail in the drop-down menu. If this button and menu are greyed out, it means that no jails are running. Start the desired jail in Warden® and click the “Jail Check” button to tell AppCafe® to look for the running jail.

−

* '''Show Jail:''' this option will show the list of running jails. Highlight the desired jail to view its installed applications.

The “Browser View” menu determines which software appears in the “Browse for Apps” tab and the results of a software search. By default, the following options are checked: “Graphical Apps” (white window with blue stripe icon), “Text Apps” (black terminal icon), and “Server Apps” (blue globe icon).

The “Browser View” menu determines which software appears in the “Browse for Apps” tab and the results of a software search. By default, the following options are checked: “Graphical Apps” (white window with blue stripe icon), “Text Apps” (black terminal icon), and “Server Apps” (blue globe icon).

+

<!--T:127-->

To also view packages, check the box for “Raw Packages” (brown box icon). It may take a minute or two for the list of available packages to populate.

To also view packages, check the box for “Raw Packages” (brown box icon). It may take a minute or two for the list of available packages to populate.

+

<!--T:128-->

Any combination of checked boxes is supported, making it easier to zero in on the types of applications one is interested in finding.

Any combination of checked boxes is supported, making it easier to zero in on the types of applications one is interested in finding.

−

===Using the CLI pkg Utilities===

+

===Using the CLI pkg Utilities=== <!--T:129-->

−

PC-BSD® uses pkgng, the next generation package management system for FreeBSD. All of the PC-BSD® utilities that deal with installing or updating non-PBI software now use the pkgng system. This allows users to safely install non-PBI software from the command line without that software being deleted by a system upgrade.

+

<!--T:130-->

+

For managing packages from the command line, PC-BSD® uses pkgng, the next generation package management system for FreeBSD. To manage PBIs from the command line, refer to [[PBI_Manager/10.1|PBI Manager]].

+

<!--T:131-->

If you are used to using the traditional FreeBSD package system, take note that the commands used to install and manage software differ slightly. For example, instead of using '''pkg_add''' to install a package from a remote repository, use '''pkg install''' or '''pc-pkg install''' (notice there is now a space instead of an underscore).

If you are used to using the traditional FreeBSD package system, take note that the commands used to install and manage software differ slightly. For example, instead of using '''pkg_add''' to install a package from a remote repository, use '''pkg install''' or '''pc-pkg install''' (notice there is now a space instead of an underscore).

−

The {{citelink|fbsdh|url=pkgng-intro.html|txt=FreeBSD Handbook}} provides an introduction to using pkgng. Section 5.5.1 is not needed on a PC-BSD® or TrueOS® system as the operating system installation does this for you. The various pkgng commands have associated man pages. Type '''man pkg''' for an overview of general usage; the names of the associated man pages will be found towards the bottom of this man page. Once you know the name of a command, you can also use the built-in help system to get more information about that command. For example, to learn more about '''pkg install''', type '''pkg help install'''.

+

<!--T:132-->

+

The {{citelink|fbsdh|url=pkgng-intro.html|txt=FreeBSD Handbook}} provides an introduction to using pkgng. Section 5.4.1 is not needed on a PC-BSD® or TrueOS® system as the operating system installation does this for you. The various pkgng commands have associated man pages. Type '''man pkg''' for an overview of general usage; the names of the associated man pages will be found towards the bottom of this man page. Once you know the name of a command, you can also use the built-in help system to get more information about that command. For example, to learn more about '''pkg install''', type '''pkg help install'''.

+

+

====Upgrading Packages==== <!--T:133-->

−

====Upgrading Packages====

+

<!--T:134-->

+

In addition to the '''pkg upgrade''' command provided by pkgng, PC-BSD® provides the '''pc-updatemanager''' command for upgrading packages.

−

To determine if newer versions of packages are available, type the following command as the superuser.

+

<!--T:135-->

+

To determine if newer versions of packages are available using this command, type the following as the superuser:

−

{{txtbox|box='''pc-updatemanager pkgcheck'''{{nbsp|55}}

+

<!--T:136-->

+

{{txtbox|box='''sudo pc-updatemanager pkgcheck'''{{nbsp|55}}

{{nbsp}} Updating repository catalogue

{{nbsp}} Updating repository catalogue

{{nbsp}} Upgrades have been requested for the following 253 packages:

{{nbsp}} Upgrades have been requested for the following 253 packages:

Line 221:

Line 276:

{{nbsp}} To start the upgrade run "/usr/local/bin/pc-updatemanager pkgupdate"}}

{{nbsp}} To start the upgrade run "/usr/local/bin/pc-updatemanager pkgupdate"}}

+

<!--T:137-->

In this example, newer versions are available for 253 packages. The list of package names was snipped from the sample output. If no updates were available, the output would have instead said "All packages are up to date!".

In this example, newer versions are available for 253 packages. The list of package names was snipped from the sample output. If no updates were available, the output would have instead said "All packages are up to date!".

+

<!--T:138-->

If updates are available, you can install them with this command:

If updates are available, you can install them with this command:

−

{{txtbox|box='''pc-updatemanager pkgupdate'''{{nbsp|54}}

+

<!--T:139-->

+

{{txtbox|box='''sudo pc-updatemanager pkgupdate'''{{nbsp|54}}

{{nbsp}} Updating repository catalogue

{{nbsp}} Updating repository catalogue

{{nbsp}} snip downloading and reinstalling output

{{nbsp}} snip downloading and reinstalling output

Line 231:

Line 289:

{{nbsp}} Extracting desktop overlay data...DONE}}

{{nbsp}} Extracting desktop overlay data...DONE}}

+

<!--T:140-->

While the output has been snipped from this example, the update process will download the latest versions of the packages which need updating, displaying the download progress for each file. Once the downloads are complete, it will display the reinstallation process for each file. The last step of the update process is to extract the desktop (or server) overlay and then to return the prompt.

While the output has been snipped from this example, the update process will download the latest versions of the packages which need updating, displaying the download progress for each file. Once the downloads are complete, it will display the reinstallation process for each file. The last step of the update process is to extract the desktop (or server) overlay and then to return the prompt.

+

<!--T:141-->

How long the package upgrade takes depends upon the number of packages and the speed of the Internet connection. If you run this command on a desktop, you should log out and log in again so that you load the latest version of the desktop and its applications. If you run this command on a server while running the tcsh shell, type '''rehash''' in order to tell the shell that new applications have been installed.

How long the package upgrade takes depends upon the number of packages and the speed of the Internet connection. If you run this command on a desktop, you should log out and log in again so that you load the latest version of the desktop and its applications. If you run this command on a server while running the tcsh shell, type '''rehash''' in order to tell the shell that new applications have been installed.

Revision as of 11:39, 18 June 2014

AppCafe®Protection (edit): Edited by: Drulavigne

AppCafe® provides an intuitive, graphical method for installing, managing, and upgrading PBIs and packages. AppCafe® does not require the root password to install software. This means that you do not have to give out the root password on multi-user systems. However, it will prompt for the user's password and will fail if that user is not a member of the wheel group. This allows you to control which users are able to manage software.

If you prefer to manage PBIs from the command line, see the section on using the PBI Manager suite of command line utilities. Refer to Using the CLI pkg Utilities for instructions on managing packages from the command line.

Finding and Installing and Software

To manage software, start AppCafe® by double-clicking its icon on the Desktop, going to Control Panel → AppCafe®, or by typing pc-su pc-softwaremanager from a command prompt. When prompted, input your password. As seen in Figure 7.1a, AppCafe® will open into the “Browse for Apps” tab.

In the example shown in Figure 7.1a, 2,172 PBIs and 23,343 packages are currently available. This tab provides several buttons and panes:

Figure 7.1a: Browsing Software Using AppCafe®

Back button: click the drop-down menu to return to a previous search or category.

Home button: click this button to return back to this initial screen.

Browse Categories button: click this button to access a list of software categories. Click on the name of a software category to browse for its available software.

Search bar/button: if you know the name of the application you would like to install, type its name into the “Search Here” bar and either press enter or click the search (binoculars) button.

Application Spotlight pane: software the PC-BSD® team recommends as being notable for their software category.

PC-BSD Recommendations pane: a list of essential applications for new users.

New pane: software which has been recently added to the AppCafe®.

In the example shown in Figure 7.1b, the user searched for the “gimp” application, then clicked the search result.

Figure 7.1b: Browsing the Information Available for a PBI

Figure 7.1c: Viewing the Information for an Installed Application

The following information is available for each application. Note that the rating and tips information is interactive, allowing users to share their tips with other PC-BSD® users. In order to do so, first create a wiki account at the PC-BSD® wiki[1], click on the activation email for the account, and login.

The software category for the application. In this case, “Gimp” is in the “Graphics” category.

Name and icon of the application.

A hyperlink to the application's website. In this example, clicking "GIMP Team" will open gimp.org in the user's default web browser.

A rating of up to five stars. Click the stars to open the PC-BSD® wiki page for the application. If you login to the wiki and hover the mouse over the number of stars to select, it will add your ranking and increment the vote number. If you make a mistake in your vote, refresh the browser, click the “remove” button, and re-select the desired number of stars.

A “User Tips” link. Click the link to open the PC-BSD® wiki page for the application. If you login to the wiki, you can add your own usage tips for the application.

An "Install Now!" icon. If the application is already installed, this will either be an "Upgrade" icon (if a newer version is available) or a "Downgrade" button (if the previous version is available).

The version of the application.

The download size.

The application's version and platform (32-bit or 64-bit). If the application only provides a 32-bit version, AppCafe® will install the 32-bit application and PC-BSD® will still be able to run the program.

The license used by the software.

The type will indicate whether the application is graphical or text (command line).

The following tabs are also available. If a tab is greyed out, it means that that information is not currently available for this particular application.

Description: of the software.

Screenshots: click the “View Full Size” button under the screenshot to view the full screen version of the screenshot.

Plugins: provides an installable list of associated plugins. For an example, search for “firefox” and open its “Plugins” tab.

Similar: provides an installable list of applications that provide similar functionality.

Build Options: shows the values of the make options that the PBI or package was built with.

Figure 7.1d: Viewing the List of Installed Software in AppCafe®

Once you find a PBI that you would like to install, click on its “Install Now!” icon. A yellow status bar at the bottom of the screen will show the download and installation status. Once the installation is complete, some of the contents of this screen will change, as seen in the example in Figure 7.1c.

The “Install Now!” button will change to “Installed” and the following buttons are now available:

Launch: provides a drop-down menu for starting the application from its available start modes. Some applications start in graphical mode, some in command-line mode, and some offer both modes.

Contact Maintainer: if this button is clicked, a pop-up message offers to launch the default email client, if one has been configured. It also indicates the email address of the FreeBSD port maintainer for that application in case one prefers to manually open their email client. If a default email client is configured, it will automatically fill in this email address as well as the important information regarding the PBI such as the build date, architecture, FreeBSD version, and version number. This allows you to send an error report or a patch to the maintainer.

Shortcuts: click this button to add or remove a desktop shortcut to the application.

Managing Installed Software

To manage software that is currently installed, use the “Installed” tab. Figure 7.1d shows a screenshot of this tab after “gimp” is successfully installed.

Figure 7.1e: Upgrading Installed PBIs

The list of installed applications can be sorted by “Program name”, “Version”, “Status” (of any running/pending “Actions”), “Size”, “Installed” (date of installation), and “Architecture”. Click the name of the desired column to change the sorting.

If you check the box for at least one installed application and click the “Actions” button, the following actions become available:

Desktop Icons: used to add or remove a shortcut to the application on any installed desktop that supports icons.

Version Lock: used to “Lock Current Version” so that it will not be updated until “Unlock Application” is selected. An application that is locked will have a lock icon next to its “Version”. Locking an application can be appropriate if there is a known issue in a more recent version of the application.

Uninstall: will uninstall the checked applications. Once the removal is complete, that software will be removed from the “Installed” list.

Cancel Actions: cancels any currently pending or running operations such as uninstallation, updating, or installation.

If you click the “Application Details” button, it will display the details for the application, as seen in the example shown in Figure 7.1c.

Updating Installed Software

As seen in the previous screenshots, AppCafe® will indicate if “Application updates are available!”. This message will automatically appear when any installed software has a newer version available. To start an update, click the “Start Updates” button. This will open the screen shown in Figure 7.1e.

In this example, the “Show Details” button was clicked in order to view the list of outdated software. The listing will show the current version as well as the newer version for the software as well as any affected dependencies and will end with the size for the amount of new software to be downloaded. Click “Yes” to start the upgrade or “No” to cancel the upgrade request.

As seen in Figure 7.1f, pnce the upgrade is started, a status bar will indicate the progress of the download and upgrade process in an “Overview” tab. To see more detailed messages, click the “Update Details” tab. The upgrade process will save all of the current version's settings. For example, when Firefox is upgraded, it will keep all of your bookmarks, history, and cache.

Figure 7.1f Watching the Upgrade Progress

This screen will indicate when the upgrade is finished and will offer to reboot the system if the upgrade requires a reboot. If a reboot is needed and you cancel it, finish saving your work then reboot the system manually.

File Menu

The “File” menu provides the following options:

Vulnerability Info: if you click this menu option, the FreshPorts VuXML page will open in the default web browser. This contains a list of all known vulnerabilities to software which has been ported to FreeBSD, and is thus available for installation in PC-BSD®. By default, the most recent vulnerabilities are shown first. There is a link on that web page to order the list of vulnerabilities by package name.

Import PBI List: if you click this option, it will ask you to browse to the location of an existing PBI list, an ASCII text file ending with a .pbilist extension that contains the names of PBIs (without a version number), one per line. An example is seen in Example 7.1a. If you import a PBI list into AppCafe®, it will add those applications to the installation queue so that they can be installed. AppCafe® will ignore any invalid lines and PBIs which are already installed.

Export PBI List: if you click this option on a system that already has PBIs installed, you can then import that list into another PC-BSD® system. By default, the exported list will be saved as exportfile.pbilist.

Quit: click this option to close AppCafe®.

Example 7.1a: Sample PBI List

apacheopenoffice

thunderbird
firefox
qtcreator
scite
gimp
pithos
quassel
ksnapshot

openjdk7

Configure Menu

The "Configure" menu contains the following options:

Repository Settings: as seen in Figure 7.1g, this option is used to select the package set. "Production" is the default and recommended setting for most users. Software updates are provided every three months, which gives sufficient time for new software versions to be tested. "Edge" is meant for users who wish to assist with software testing or who can tolerate the occasional breakage caused by installing new software versions. Software updates are provided approximately every two weeks. "Custom" is for administrators who have created their own PBI repository; click the “+” button to browse to the location of the custom .rpo file. To allow switching between custom repositories, multiple custom repositories can be listed, but only the one marked as active will be used.

Refresh PBI Index: click this option to get the latest copy of the list of available PBIs and packages. Otherwise, this list is automatically refreshed each time AppCafe® is started.

Developer Mode: check this box to add a pane of debugging messages to the bottom of AppCafe®. This can be useful to help determine the problem if there is an error in installing or upgrading software.

Figure 7.1g: AppCafe® Repository Settings Menu

Install View Menu

The default AppCafe® view only provides information about PBIs but does not provide information about packages. This means that the “Installed” tab will only show installed PBIs and the “Browse for Apps” tab and search function will only display available PBIs. This default can be changed using the options in the “Install View” menu, which changes the appearance of the "Install" tab, and “Browser View” menu, which changes the appearance of the "Browse for Apps" tab.

The “Install View” menu contains the following options:

Show Raw Packages: when this box is checked, it adds the list of installed packages to the list of installed PBIs. An example is seen in Figure 7.1h.

Show Orphan Packages: when this box is checked, the contents of the “Installed” tab change to the list of installed software which are not dependencies of any other installed application. An example is shown in Figure 7.1i. The list will either be PBIs or PBIs and packages, depending upon whether or not “Show Raw Packages” is also checked.

Show Base Packages: when this box is checked, the contents of the “Installed” tab change to the list of installed base system packages, or the packages which get installed with the operating system. If “Show Raw Packages” is also checked, the listing will include every installed package rather than just the name of the system component. An example is seen in Figure 7.1j.

Figure 7.1h: List of Raw Packages

Figure 7.1i: List of Orphan Packages

Figure 7.1j: List of Base Packages

By default, AppCafe® displays software information for the computer running PC-BSD®. It can also be used to manage the software running in a jail, as long as at least one jail has been created and is running. To manage a jail, click the “Jail” button and select the name of the jail in the drop-down menu. If this button and menu are greyed out, it means that no jails are running. Start the desired jail in Warden® and click the “Jail Check” button to tell AppCafe® to look for the running jail.

Browser View Menu

The “Browser View” menu determines which software appears in the “Browse for Apps” tab and the results of a software search. By default, the following options are checked: “Graphical Apps” (white window with blue stripe icon), “Text Apps” (black terminal icon), and “Server Apps” (blue globe icon).

To also view packages, check the box for “Raw Packages” (brown box icon). It may take a minute or two for the list of available packages to populate.

Any combination of checked boxes is supported, making it easier to zero in on the types of applications one is interested in finding.

Using the CLI pkg Utilities

For managing packages from the command line, PC-BSD® uses pkgng, the next generation package management system for FreeBSD. To manage PBIs from the command line, refer to PBI Manager.

If you are used to using the traditional FreeBSD package system, take note that the commands used to install and manage software differ slightly. For example, instead of using pkg_add to install a package from a remote repository, use pkg install or pc-pkg install (notice there is now a space instead of an underscore).

The FreeBSD Handbook[2] provides an introduction to using pkgng. Section 5.4.1 is not needed on a PC-BSD® or TrueOS® system as the operating system installation does this for you. The various pkgng commands have associated man pages. Type man pkg for an overview of general usage; the names of the associated man pages will be found towards the bottom of this man page. Once you know the name of a command, you can also use the built-in help system to get more information about that command. For example, to learn more about pkg install, type pkg help install.

Upgrading Packages

In addition to the pkg upgrade command provided by pkgng, PC-BSD® provides the pc-updatemanager command for upgrading packages.

To determine if newer versions of packages are available using this command, type the following as the superuser:

sudo pc-updatemanager pkgcheck

Updating repository catalogue
Upgrades have been requested for the following 253 packages:
list of packages snipped
The upgrade will require 70 MB more space
439 MB to be downloaded

To start the upgrade run "/usr/local/bin/pc-updatemanager pkgupdate"

In this example, newer versions are available for 253 packages. The list of package names was snipped from the sample output. If no updates were available, the output would have instead said "All packages are up to date!".

While the output has been snipped from this example, the update process will download the latest versions of the packages which need updating, displaying the download progress for each file. Once the downloads are complete, it will display the reinstallation process for each file. The last step of the update process is to extract the desktop (or server) overlay and then to return the prompt.

How long the package upgrade takes depends upon the number of packages and the speed of the Internet connection. If you run this command on a desktop, you should log out and log in again so that you load the latest version of the desktop and its applications. If you run this command on a server while running the tcsh shell, type rehash in order to tell the shell that new applications have been installed.