Revision as of 05:11, 6 May 2009

This page is under construction.
You are welcome to assist in its construction by editing it as well.
This message should be deleted after editing.

PİSİ (Packages Installed Successfully as Intended) is a binary package management system which have been developed within Pardus project. PİSİ has more function than just installing/uninstalling packages. For example, it is possible to regain old package setup atomatically. Packages need to be processed as pisi packages and presented as binary packages for using them as pisi packages. For detailed information you can look at Pardus official site

Basics

Package: A program, document or any kind of data for installing to system

Source file: A file that includes files which belongs to package and generally presented as archive files and generally downloadable via internet. Programs generally uses files that are archived as .tar.gz files. Archived files need to include program's non-compiled source code, data that program needs and documents.

Compiling: Operation that needs to be done to make exectuable binary files of programs that is written in compilable programing language like C,C++.

Dependency: Other packages that program uses while it is running or compiling.

Integrity code: This code is being used to verify that any downloaded data has been succesfully downloaded without getting damaged. Sites generally put integrity codes obtained by md5 or sha algorithms for source files. Verifing is done by compraing this code and the code obtained from downloaded data.

Packager's point of view

Adding package to pisi system is more than just making a pisi package. It is a process including gathering information about the package you want to make pisi package of, testing and debugging your pisi package, keeping up with newer versions. A user should start building pisi packages only if user thinks s/he can follow this process. Pisi packages are like the children of the packager and hets replenished with every single debugging and version change. However, unsupervised packages can't live long in the linux world which is growing rapidly. People shouldn't make pisi packages as many as they can, but should make pisi packages as many as they can keep track of. And also don't forget to share your packages from the internet as Linux world is one of the best examples of colloective working. By doing so, you can also find other users who can help you with debugging and keeping track of your package.

Packaging Mechanism

This mechanism is a mechanism that makes binary packages that pisi uses by using source codes. If we omit technical details, process is like following:

• Source codes get downloaded by processing "Source" part of the pspec.xml file and after it gets verified, it gets extracted to /var/pisi/package_name/work
• To obtain binary data action.py gets processes and instalation is made to /var/pisi/package_name/install using source code.
• If there is any additional file they get coppied to /install directory as it defined at pspec.xml
• Pisi makes index file for the files in the /install directory. This index is compatible with pisi database and in XML format.
• Index and binary get combined with datas obtained from pspec.xml and archived as .pisi package

As one can see, pisi installs package to /var/pisi/paket_adi/install while it produces .pisi file. Pisi behaves this directory as it were root system. By examining this directory one can monitor which files go to which directory.

Pardus SVN Repository

Pardus SVN repository is a kind of library that you can examine pardus projects and the source files of pisi packages that developers made. You can check how developers made pisi packages for similiar packages that you want to make a pisi package for. You can access this repository from here. At that site, there is pisi source files of pisi packages. All answers to "how" questions that new beginners ask actually can be found in source files avaible at Pardus SVN repository.

File and Directory Locations

Mandatory packaging files that pisi requires are pspec.xml and actions.py. Both should be in same directory. "comar" and "files" directories can be used if necessary. These directories must be in same directory as pspec.xml. Source files looks like this:

package_name
      |__pspec.xml
      |__actions.py
      |__files
      |__comar
            |__package.py
            |__service.py

Structure of a PiSi Package

A pisi package is essentially a zipped file. Let's download one and examine it. To do so write following to your konsole:

$ wget http://paketler.pardus.org.tr/pardus-2008/knazar-0.2_p21206-7-3.pisi

Now that our pisi package downloaded to our current working directory, we can extract files from our pisi package. Open pisi package with "ark" and select zip archive if it asks for what kind of archive it is. After that extraxt it somewhere. You'll see there are 3 files exist: files.xml, metadata.xml and install.tar.lzma.

files.xml contains locations, types, sizes and sha1sums of all files in the package and looks like this:

<Files>
    <File>
        <Path>path/to/install/the_file.txt</Path>
        <Type>data</Type>
        <Size>1602</Size>
        <Uid>0</Uid>
        <Gid>0</Gid>
        <Mode>0644</Mode>
        <Hash>a30a14bca4a66f2519e2857027b00c31d72e3896</Hash>
    </File>
                          .
                          .
                          .
    <File>
        <Path>path/to/install/the_file.bin</Path>
        <Type>data</Type>
        <Size>1602</Size>
        <Uid>0</Uid>
        <Gid>0</Gid>
        <Mode>0644</Mode>
        <Hash>a30a14bca4a66f2519e2857027b00c31d72e3896</Hash>
    </File>
</Files>

metadata.xml contains general information like package name, homepage, packager, etc. Looks just like pspec.xml file.

install.tar.lzma contains compressed files that we can extract and have a look at. Do not hesitate to check them so you can get better understanding of a pisi package.

PiSi Package Building

In order to build a pisi package we need to prepare at least two files by hand: pspec.xml and actions.py

pspec.xml

This file is about definiton and content of package and packaging progress. XML files are like a kind of database. An XML file which has a data and a parameter which belongs to that data looks like this:

<Path fileType="executable">/usr/kde/3.5/bin</Path> 
    |      |       |                  | 
    |      |       |                  \--Data 
    |      |        \--------------------Property of data 
    |       \----------------------------Name of property
     \-----------------------------------Tag 

Basic pspec.xml structure is like following and first two lines are standart meaning you have to keep them as they are.

<?xml version="1.0" ?> 
<!DOCTYPE PISI SYSTEM "http://www.pardus.org.tr/projeler/pisi/pisi-spec.dtd"> 
<PISI> 

  <Package> 
       ... 
  </Package> 
 
   <History> 
       ... 
   </History> 
 
</PISI> 

Lots of tags exist at these parts of pspec.xml and some of them are special. Possible datas that these special tags can hold are predefined so that they can be indentified by Pardus system. Values that these tags can hold and information about usage of these tags are gathered in a Relax NG (rng) file by Pardus developers. These rng files are scheme files that can be used for getting information about tags within a XML file. Every tag is defined here within a scheme. rng files has a structure that can easily get understanded because this structure is same as a XML structure.

Most up-to-date version of rng scheme of pspec.xml is accessible via http://svn.pardus.org.tr/uludag/trunk/pisi/pisi-spec.rng. Easiest way to find information about a tag is to make a search for <!-- tag -->

Source part

This part gives basic information about package to pisi. In addition, which category and part that package belongs in Pardus system structure, which packages need to exist while compiling, which patches need to applied before compiling process are also defined here. Basically this part looks like this:

IsA tag and PartOf tag are the tags that people mostly waver about.

IsA tag required to determine which category that package belongs so that packages belong to same category can be listed together using a interface like package-manager. This tag can be defined more than once. You can check for available datas that this tag can hold in pisi-spec.rng file.

PartOf tag is for determining which component that package belongs at the system. So that users can make mass operations about a component group. For example, you can install all of kde4 related packages using:

$ sudo pisi it -c desktop.kde4

To see all component group names and desriptions write this to your console:

 $ pisi list-components

You can decide which group does your package belong checking the output of code above.

If integrity code of source code cannot be found on web-site of package, you can find it using "sha1sum file_name" code.

Installation of Additional Files from the Files Of the Source Tree

The Package may contain the AdditionalFiles tag, which can be used to copy files from the files subdirectory of your source tree into the .pisi.

E.g., suppose I have a structure like so:

myproject/
myproject/files/somefile.config
myproject/actions.py
myproject/pspec.xml

Then, (one of) the Package(s) can have the following:

   <Package>
       <Name>myproject</Name>
       <Summary>Core of MyProject.</Summary>
       <RuntimeDependencies>
           <Dependency>some-lib</Dependency>
       </RuntimeDependencies>
       <Files>
           <Path fileType="executable">/usr/bin</Path>
       </Files>
       <AdditionalFiles>
           <AdditionalFile target="/etc/path/to/install" permission="0644"                                 
                           owner="root">somefile.config</AdditionalFile>
       </AdditionalFiles>
   </Package>

actions.py

This file contains python codes that would compile and install the source package into a specific InstallDIR (in our example it is /var/pisi/knazar-0.2-3-3/install/)

http://svn.pardus.org.tr/pardus/devel/desktop/kde/knazar/actions.py

In this file, we use actionsapi that comes with pisi. Actions API has all functions for us to compile and install our package.

If you know python, you may want to have a look at sources here: http://svn.pardus.org.tr/uludag/trunk/pisi/pisi/actionsapi/

After preparing pspec.xml and actions.py you can easily form a pisi package by typing:

sudo pisi build pspec.xml

in the console. To compile my example you may type:

sudo pisi bi http://svn.pardus.org.tr/pardus/devel/desktop/kde/knazar/pspec.xml

Finally, you can examine other official pisi source packages here: http://svn.pardus.org.tr/pardus/devel/