Differences

This shows you the differences between two versions of the page.

--- etc:20-lpm-gui [2022/05/14 01:21] – wikiadmin
+++ etc:20-lpm-gui [2022/07/28 18:13] (current) – wikiadmin
@@ Line 55: / Line 55: @@
 As archive format, lpk uses gzip compressed cpio, prepended by a header containing the package information. The prepended header looks like this:
-  * 11 bytes made from 5 bytes containing the version signature (EPLM20) and 6 bytes containing the zero-padded size of the following header
+  * 11 bytes made from 5 bytes containing the version signature (ELPM20) and 6 bytes containing the zero-padded size of the following header
   * The package description, starting at byte 12.
@@ Line 92: / Line 92: @@
 </code>
-The used text format is basically ldif, as described [[https://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format|here ]]. It allows multiple values per attribute (elpkDependency), as well as base64 encoded binary data  (elpkRsaSigData) and is quite easy to parse, and much easier on the eye as XML.
+The used text format is basically ldif, as described [[https://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format|here ]]. It allows multiple values per attribute (elpkDependency), as well as base64 encoded binary data (elpkRsaSigData) and is quite easy to parse, and much easier on the eye as XML.
 ==== 3.1 Package scripts ====
@@ Line 130: / Line 130: @@
 Per default, lpm brings along a simple directory-based lpc called lpc-dirs, which is great for testing purposes and also for an initial distro installation. As part of its source code, lpm also contains the lpc-http lpc, which allows to access remote package catalogues over http and also ftp.
+===== 5. Basic information for creating lpm frontends =====
+In order to create an lpm frontend, you first have to download its complete source code, as there is no separate development package with only the needed parts available. This can be done via git:
 <code>
@@ Line 137: / Line 141: @@
 </code>
+After building lpm successfully, the source directory will then contain the files liblpm.a and lpm.h that will contain all definitions and functions needed to create another working front end.
+The main lpm frontend program (main.c) also implements all its functionality using those two files.
+When creating another frontend for lpm, it is however advisable to only implement the non-prvileged parts directly and use the privileged plpm program for any actual package installations or updates. This is due to the fact that installs and updates require root privileges, and all gui frameworks strongly discourage running gui programs as root.
+plpm is a reduced commandline program always running as root, but only allowing to be used by members of a defined group. It is therefore the preferred method to let a gui program perform any privileged action. It also implements a simple call to check if the user is allowed to use it, so a gui frontend can find out early on if the used is allowed to install packages.
+===== 6. The sample lpmsh frontend =====
+In the subdirectoey guix, there is a file called lpmsh.c, implementing a sample lpm frontend in form as a shell. The shell example was chosen, as it:
+  * needs minimal additional code for its implementation
+  * has a division of startup code and a loop implementing several functions
+It therefore might server as a good reference of how a gui might call the lpm funcions and process their data.
+===== 7. plplm usage =====
+plpm implements the following commands:
+  * allowed: This takes no argument and will return 0 if the user is allowed to use plpm.
+  * refresh: This takes no argument and will refresh the currently used package catalogue
+  * cleanup: This takes no argument and will clean the stagearea from package files
+  * install: This takes arguments described below and will install new packages
+  * upgrade: This may take arguments and will update installed packages
+If upgrade is called without arguments, it will update all packages where a new version is available
+Otherwise, both upgrade and install may be called with one or more package names to be installed or updated
+If only one package is specified, the caller may also first specify a specific version and/or variant to be used.
+The usage is then as follows:
+<code>
+plpm install|upgrade -o version=$my_version,variant=$my_variant $my_package
+</code>
+In all other cases, the usage is:
+<code>
+plpm install|upgrade $package_1 $package_2 ...
+</code>
+The function plpm_exec in lpmsh.c provides a working example on how to call plpm in all cases.
+===== 8. Important frontend data structures =====
+==== 8.1 LPI ====
+Most relevant structures and functions are defined in the header file lpm.h, the most important structure is:
+<code>
+struct s_lpk_info {
+    char *name;
+    char *variant;
+    char *version;
+    char *creator;
+    int arch;
+    char *desc;
+    char *clog;
+    char **deps;
+    int removable;
+    unsigned long datasize;
+    /* The next two are only for repository packages */
+    unsigned long filesize;
+    char *filehash;
+    char *abs_uri;
+    char *rel_uri;
+    /* These three are only for locally installed packages */
+    time_t install_time;
+    char  install_type;
+    char *install_head;
+    time_t *update_time;
+    /* The next three are for the signature */
+    char *rsa_sig_subj;
+    char *rsa_sig_data_buf;
+    int rsa_sig_data_len;
+    int rsa_verified;
+    /* Now follows a ekva with any further extended attributes */
+    struct s_ekva **ext_attributes;
+};
+typedef struct s_lpk_info LPI;
+</code>
+LPI is used throughout lpm for any package information, either for installed packages, available packages or package files. It contains all relevant information of any package, but not its actual contents. Consequently, all functions that will return information about one or more packages with either return one LPI, or an array of LPI's.
+The meaning of its members are:
+|name|the package name|
+|variant|the package variant, can be NULL|
+|version|the package version|
+|creator|name and mail address of the package creator|
+|arch|either i686,x86_64,mips or any, largely unused|
+|desc|the package description|
+|clog|the package's changelog, unused|
+|deps|an array of names of the package's dependencies, can be NULL|
+|removable|boolean of package is removable, absolutely unused|
+|datasize|the sum of bytes in the data part of a package|
+|filesize|the filesize of a package in lpc catalogue|
+|abs_uri|the absolute uri of a package in lpc catalogue|
+|rel_url|the relative uri of a package in lpc catalogue|
+|install_time|the installation unix time of an installed package|
+|install_type| \\ X for an installed package if explicitely installed, D if installed as a dependency|
+|install_head|if installed as a dependency, the name of the package having required it|
+|update_time|an array of unix time when the package was updated, can be NULL|
+|rsa_sig_data|the buffer and it's size containing the package's signature|
+|rsa_sig_subj|the subject dn of the package signer|
+|rsa_verified|a flag containing the vefication status|
+|ext_attributes|an EKVA of other package attributes, currently unused|
+| | |
+==== 8.2 EKVA ====
+EKVA is an array of stuctures containg a pointer to a key and to a value and is defined in stuff/ekva.h:
+<code>
+struct s_ekva {
+    char *key;
+    char *val;
+};
+typedef struct s_ekva EKVA;
+</code>
+EKVA arrays are used extensively throughout lpm as text-based keyword-value stores, with multiple values for one keyword possible depending on its initialisation. As their first element, they hold a header containing their current size an mode, allowing for automatic growing and management of multiple values.
+EKVA arrays are created, filled, read and deleted by a set of functions defined in ekva.h, the most important ones being:
+- ekva_new: to create a new EKVA array \\ - ekva_addval: to add a key/val pair to the EKVA arrray \\ - ekva_getval: to read the first value for a key \\ - ekva_cntval: to count the number of vaules for a key \\ - ekva_getone: to read the specified value for a key \\ - ekva_getvals: to read all values for a key
+==== 8.3 LPA ====
+LPA arrays are used to store information about available updates in an easily parsable form:
+<code>
+struct s_lpa {
+    char action;
+    char status;
+    LPI *lpi;
+    char *candidate;
+};
+typedef struct s_lpa LPA;
+</code>
+- action is 'U' or 'I', as an update might pull a new dependency \\ - status is always 'N' \\ - lpi contains the package info of the package to be installed or updated
+===== 9. important frontend functions =====
+All frontend functions are defined int lpm.h, the ones relevant to a frontend using plpm for privileged actions are:
+- lpm_open: "opens" the local lpm repository and return an LPM * structure for further use.
+- lpmui_init: initializes the internally used lpmui, necessary, but has no effect…
+- lpm_lpc_load: loads the configured package catalogue
+- lpm_lpc_connect: connects the program to the package catalogie
+- lpm_lpc_cache_fill: fills the package catalogue cache
+- lpm_lpc_release: disconnects from the package catalogue
+- lpm_cache_free: frees the cache
+- lpk_info_ekva: converts an LPI * package description to a string-based EKVA * keyword/value list
+- lpm_list_lpi: returns a list of locally installed package descriptions
+- lpm_lpf_info: returns a package description from a package file
+- lpm_findpkg_new: returns a list of available, not installed packages
+- lconf_read: reads the lpm config file
+- log_init: initializes the internal logging mechanism, necessary
+- lpm_pre_update: checks for an available update of a specified package
+- lpm_lpa_list_add_lpt: adds the results of lpm_pre_update to an easily readable LPA * list
+===== 10. Required globals =====
+In order for the frontend to be able to use all further funtions correctly, it has to define a set of global variables:
+<code>
+void *lpc_backend_handle;
+EKVA **lpm_sys_conf = NULL;
+LPC *lpc;
+int dry_run =  0;
+int vote_mode = LPM_VOTE_DEFAULT;
+LPMUI *lpmui = NULL;
+struct s_llog *llog;
+LPI **lpc_cache;
+</code>
+===== 11. Required initialization sequence =====
+Maybe in later releases, the initialisation sequence will be simplyfied and merged into some lpm_init function, but for the moment, the code from line 490 - 542 from lpmsh.c can be copied for that purpose.