[HOWTO] Use PPM to download and activate modules

Post tutorials, HOWTO's and other useful resources here.
User avatar
Ahau
King of Docs
King of Docs
Posts: 1331
Joined: 28 Dec 2010, 15:18
Distribution: LXDE & Xfce 32/64-bit
Location: USA

[HOWTO] Use PPM to download and activate modules

Post#1 by Ahau » 17 Jun 2011, 17:37

I've slapped this together, hoping to get it completed prior to the release of V1.0 FINAL. I'm sure it contains some incorrect information, so consider this a rough draft -- brokenman, feel free to edit this post directly if you would like.

I find PPM to be easy to use and self-explanatory, so this document may wind up being largely unneccessary. If nothing else, we'll have a long document on the website that advertises the location of this wonderful new tool :)

Many thanks to brokenman -- I'm really excited about PPM!


----------------------
HOWTO use the Porteus Package Manager (PPM)

As of Version 1.0, Porteus includes a new tool called Porteus Package Manager. This utility is designed to allow users to download and activate packages from the Porteus server in module (xzm) format. PPM is designed to automatically detect and download any dependencies for the packages you select. Also, if all of the dependencies are not located on the Porteus server, PPM will search the Slackware repositories for the missing dependency, download it to your system, and convert it to a Porteus module.

To use PPM, you can either type 'porteus-package-manager' from a console, or select 'Porteus-Package-Manager-PPM' from the KDE or LXDE menu, under "System". If you are running as a non-root user, you will be prompted for the root password (toor by default).

This opens up the PPM Welcome Screen, which gives you some information about modules and how the program works. Read the information, then press "OK".

On the next screen, you will be asked to select a directory where you would like to store all of the modules that you download with PPM. You can choose any location you like, but the most convenient location for typical users is on the same storage medium as their Porteus install, either in /porteus/modules or /porteus/optional. If you place your modules in /portues/modules, they will be activated automatically and available for use every time you start up Porteus. If you place them in /porteus/optional, they will not be activated automatically at startup --rather, you can activate them on demand while Porteus is running. If you have many modules that you don't use regularly, keeping them in /porteus/optional will help keep your live system tidy and free of extra programs and files.

To select a folder for your modules, double click on your desired device (e.g. sdb1) or '../' to move into the root directory. Then, continue double clicking on the folders down the path to where you want your modules stored, e.g. 'porteus', then 'modules'. You can use the 'New Folder' button at the top to create a new directory in your current location if you would like. After double clicking to enter the folder where you want to store your modules, click on the 'OK' button. You will be asked to confirm your choice (e.g. /mnt/sdb1/porteus/modules) -- verify the location is correct, then press 'Yes'.

The next screen is the PPM main menu. You are given several options to choose from. If this is your first time running PPM or if it's been a while since you've used it, you should first update your index files to make sure PPM has the latest package listings from the Porteus repository. To do this, select the 'Update index files' option, choose (yes? ok?), then wait for the files to download. Press 'OK' when it's done to return to the main menu.

Once you've updated your index, you are ready to find a module to download! At the top of PPM's main menu are four ways to search for modules -- by category, name, keywords, or libraries. Each option should be relatively self explanatory. The 'search by libraries' option can be particularly useful if you have a program that complains of missing libraries when you try to run it (when run from the command line, an error is typically given naming the library that is missing). PPM will search the list of files included in each package to look for that specific library file, and show you the package in which it is included.

Let's walk through the process for installing a module through the "search by category" option:

Double click on the "search by module category" option. This brings up a list of several categories to choose from. Double click on the category for the application you would like to install, e.g., 'graphics'. You will be presented with a list of packages within that category. Double click on the program you would like to download, e.g. 'cinepaint-0.22.1-i4865sl.xzm'. This brings up a description of the package, it's size, what it does, etc. Click on the "I want it!" button to download, or the "Go Back" button to return to the main menu to search for a different package.

If you click "I want it!", you will be presented with information about dependencies for this program. Using the example of 'Cinepaint' above, Porteus will need to download three additional packages in order for Cinepaint to run. If any of the necessary packages are not on the Porteus Server, PPM will search the Slackware repositories for them, and if they are found they will be listed under the heading "These files will be downloaded from the slackware server". Any packages that you have already downloaded with PPM will show up under, "These files already exist in your storage folder".

Click on the "Download now" button to continue. Your program and all of its dependencies will then be downloaded to the folder you selected when you first started PPM. Any packages that were not in the Porteus repo that were found in a Slackware repo will also be downloaded and you will be asked to convert them to Porteus modules. This process is automated by the script; however, it will ask you to identify which category this package belongs in. Simply review the description that is provided, then select a category for it. If you do not plan to share this module with others, it doesn't really matter which category you choose.

Once PPM completes downloading all of the modules, you will be asked whether or not you would like to merge all of the modules together. This can be useful if you are activating your modules manually or if you wish to move them back and forth between locations, but it can also lead to conflicts between packages, and ...(explain all the bad stuff--brokenman help me out here?)...

If you choose to merge your modules, they will be created and sent to the desktop of the root user, at /root/Desktop/yourmodulename-alldeps.xzm. This may take a long time depending on the size of the package. Note that all of the individual packages you downloaded will remain in the folder to which they were downloaded. If you want to use only the merged module, then you must manually delete those files, or move them to another location for storage.


Activating modules:

If you placed your modules in the /porteus/modules folder, then they will automatically be loaded the next time you start Porteus. Otherwise, you can use PPM to activate modules and all of their dependencies. To do so, open up PPM and double click on 'Activate a module' in the main menu. You are given a list of files in the folder that you specified when you first ran PPM. If you saved the module you want to activate to another location, you can navigate there in the pane on the left side of the window. Once your module is displayed in the pane on the right, you can double click to activate it. PPM will find all of the dependencies for that module on your local system and select them to be activated as well. The next screen will show you all of the modules that must be activated to use this program. Click 'OK', and all of thse modules will be activated and your program will be ready for use. You can either run it from the command line or find it in the KDE or LXDE menu.


If you run into any problems, feel free to post about them in the relavant section of our forum. PPM has an option in the main menu to generate a bug report, and you can copy the text from that report into your post on the forum to seek help from the Porteus Community.

Posted after 1 day 2 hours 11 minutes 14 seconds:
NOTE: I've added this doc to the main site, so that it will be up for the release of V1.0. I've called it out as still a draft -- suggestions/corrections are still very much welcome.
Please take a look at our online documentation, here. Suggestions are welcome!