Debian upstream: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | On Debian distribution, the upstream source is the code of the program that can be compiled for any target platform. It needs to be compilable using packages already available in the latest Debian distribution. | |
| 2 | 2 | ||
| 3 | 3 | If you want to distribute the .deb file directly, you may generate it following [[Debian package structure]]. | |
| 4 | 4 | ||
| 5 | 5 | ### Dependence on Lazarus custom packages | |
| 6 | 6 | ||
| 7 | 7 | Generally Debian packages will use dynamically linked libraries, that will be provided as another Debian package. However in Lazarus, it is common to use statically linked libraries that are provided as Lazarus custom packages (the main file have `.lpk` extension). | |
| 8 | 8 | ||
| 9 | 9 | If you are using custom Lazarus packages, you will need to include them in the upstream source. You can do that by copying the custom packages source code into your projects repository or create an upstream repository that will contain your own project as well as all custom packages source code. | |
| 10 | 10 | ||
| 11 | 11 | Publishing a new version of your project on Debian will thus require you to copy the source of used packages with the adequate version number. It is recommended to specify the required package version in the project inspector, so that you won't use an outdated custom package for compilation and also that you will be able to know which version is supposed to be used. | |
| 12 | 12 | ||
| 13 | 13 | ### Upstream source, package maintainer and sponsor | |
| 14 | 14 | ||
| 15 | 15 | There are different levels when it comes to uploading packages into Debian: | |
| 16 | 16 | ||
| 17 | 17 | - upstream source provided by the software developer | |
| 18 | 18 | - [[Debian package source]] provided by the package maintainer | |
| 19 | 19 | - upload done by the package sponsor/mentor | |
| 20 | 20 | ||
| 21 | 21 | Note that it may be difficult to find a package maintainer so that the developer can as a matter of fact be the maintainer as well. This article talks only about the upstream source. | |
| 22 | 22 | ||
| 23 | 23 | The term sponsor/mentor does not refer to a financial support but to a Debian developer. | |
| 24 | 24 | ||
| 25 | 25 | ### Upstream source content | |
| 26 | 26 | ||
| 27 | 27 | The upstream source consists of: | |
| 28 | 28 | ||
| 29 | 29 | - you project source code and custom Lazarus packages source code | |
| 30 | 30 | - compilation scripts | |
| 31 | 31 | - additional information about the program | |
| 32 | 32 | ||
| 33 | 33 | It can be organized for example like this: | |
| 34 | 34 | ||
| 35 | 35 | `upstream`\ | |
| 36 | 36 | ` ├─ myproject ... # folder for main project (containing a .lpi file)`\ | |
| 37 | 37 | ` ├─ custompackage ... # folder for custom package (containing a .lpk file)`\ | |
| 38 | 38 | ` ├─ configure # script to setup compilation`\ | |
| 39 | 39 | ` ├─ Makefile # compilation and installation script`\ | |
| 40 | 40 | ` └─ info`\ | |
| 41 | 41 | ` ├─ myproject.1 # command line manual`\ | |
| 42 | 42 | ` ├─ myproject.desktop # GUI application description`\ | |
| 43 | 43 | ` └─ icons # GUI icons`\ | |
| 44 | 44 | ` ├─ 16x16.png`\ | |
| 45 | 45 | ` ├─ 32x32.png`\ | |
| 46 | 46 | ` ...` | |
| 47 | 47 | ||
| 48 | 48 | In all cases, the `debian` folder name is reserved for the Debian package so the upstream must not contain such folder unless it takes the responsibility of describing the Debian package. | |
| 49 | 49 | ||
| 50 | 50 | Common icon sizes: 16x16, 22x22, 24x24, 32x32, 36x36, 48x48, 64x64, 256x256, scalable, symbolic. Scalable and symbolic are in SVG format. You don't need to provide all of them, they will be stretched if necessary. | |
| 51 | 51 | ||
| 52 | 52 | #### Project and custom packages | |
| 53 | 53 | ||
| 54 | 54 | It is recommended to use a specific folder for each custom package, though there is no restriction here. You just need to remember the path to those when writing the `Makefile`. | |
| 55 | 55 | ||
| 56 | 56 | #### Command line manual | |
| 57 | 57 | ||
| 58 | 58 | The syntax is of the .1 file is a bit peculiar. There are some tools to help but you still need to know the syntax. | |
| 59 | 59 | ||
| 60 | 60 | - description of the syntax: <https://liw.fi/manpages/> | |
| 61 | 61 | - editor with wizard and WYSIWYG preview mode: **gmanedit** | |
| 62 | 62 | - live preview editor (toggle to **AN mode**): <https://roperzh.github.io/grapse/> | |
| 63 | 63 | ||
| 64 | 64 | Here is a sample file: | |
| 65 | 65 | ||
| 66 | 66 | `.TH Project1 1 "19 May 2020" "" Project1`\ | |
| 67 | 67 | `.SH NAME`\ | |
| 68 | 68 | `Project1 - My cool project`\ | |
| 69 | 69 | `.SH SYNOPSIS`\ | |
| 70 | 70 | `.B project1`\ | |
| 71 | 71 | `[PARAMETER]`\ | |
| 72 | 72 | `.SH DESCRIPTION`\ | |
| 73 | 73 | `What my program does.`\ | |
| 74 | 74 | `.PP`\ | |
| 75 | 75 | `More description.` | |
| 76 | 76 | ||
| 77 | 77 | #### Application description | |
| 78 | 78 | ||
| 79 | 79 | To add your application to the Linux menu, you need to add a file called ***.desktop** containing: | |
| 80 | 80 | ||
| 81 | 81 | `[Desktop Entry]`\ | |
| 82 | 82 | `Name=Project1`\ | |
| 83 | 83 | `Comment=Cool project`\ | |
| 84 | 84 | `Icon=project1`\ | |
| 85 | 85 | `Exec=project1`\ | |
| 86 | 86 | `Terminal=false`\ | |
| 87 | 87 | `Type=Application`\ | |
| 88 | 88 | `Categories=Graphics`\ | |
| 89 | 89 | `GenericName=Project1`\ | |
| 90 | 90 | `Keywords=feature1; feature2; feature3` | |
| 91 | 91 | ||
| 92 | 92 | This file is similar to a shortcut to your program. | |
| 93 | 93 | ||
| 94 | 94 | The **Categories** field is similar to the one in the **control** file. It can be for example: Communication, Database, Development, Editors, Electronics, Fonts, Games, Graphics, Math, Internet, Networking, News, Science, Sound, Utility, Video. | |
| 95 | 95 | ||
| 96 | 96 | The keywords help search through applications. | |
| 97 | 97 | ||
| 98 | 98 | #### configure script | |
| 99 | 99 | ||
| 100 | 100 | The script called `configure` is a script that is called initially before compilation. It can be used to detect the compilation environment and take appropriate actions. In the case of Lazarus, the bare minimum is to handle the *prefix* parameter. Here is for example a simple script that will store the *prefix* parameter in a file called `prefix`. | |
| 101 | 101 | ||
| 102 | 102 | `#!/bin/bash`\ | |
| 103 | 103 | `args=("$@")`\ | |
| 104 | 104 | `defaultprefix=/usr/local`\ | |
| 105 | 105 | `wantedprefix=$defaultprefix`\ | |
| 106 | 106 | `for param in "${args[@]}"`\ | |
| 107 | 107 | `do`\ | |
| 108 | 108 | ` if [ "$param" == "-h" ] || [ "$param" == "--help" ]; then`\ | |
| 109 | 109 | ` echo "Usage: ./configure [OPTIONS]"`\ | |
| 110 | 110 | ` echo ""`\ | |
| 111 | 111 | ` echo " --prefix=PREFIX"`\ | |
| 112 | 112 | ` echo " Specifies the install prefix."`\ | |
| 113 | 113 | ` echo " By default prefix is \"$defaultprefix\"" `\ | |
| 114 | 114 | ` echo " For packages use \"/usr\""`\ | |
| 115 | 115 | ` exit 0`\ | |
| 116 | 116 | ` elif [ "${param:0:9}" == "--prefix=" ]; then`\ | |
| 117 | 117 | ` wantedprefix=${param:9}`\ | |
| 118 | 118 | ` else`\ | |
| 119 | 119 | ` echo "Warning: unknown option $param"`\ | |
| 120 | 120 | ` fi`\ | |
| 121 | 121 | `done`\ | |
| 122 | 122 | `echo "Prefix set to: $wantedprefix"`\ | |
| 123 | 123 | `echo $wantedprefix >prefix # store the prefix into the file called "prefix"` | |
| 124 | 124 | ||
| 125 | 125 | Here are examples of calls: | |
| 126 | 126 | ||
| 127 | 127 | `./configure # when testing the program locally`\ | |
| 128 | 128 | `./configure --prefix=/usr # when building the package` | |
| 129 | 129 | ||
| 130 | 130 | #### Makefile | |
| 131 | 131 | ||
| 132 | 132 | ##### Initialization | |
| 133 | 133 | ||
| 134 | 134 | The Makefile is a sort of script. It does not have a shebang (line starting with "#!") and uses by default the minimalist shell `/bin/sh`. You can override it though and use bash with something like: | |
| 135 | 135 | ||
| 136 | 136 | `SHELL := /bin/bash` | |
| 137 | 137 | ||
| 138 | 138 | Note that in the `Makefile`, unlike a regular script, to access a variable one write `$(VARIABLE)` with brackets instead of `${VARIABLE}` with braces. To run a shell command and retrieve the result, the brackets will also be used, which can be a little bit confusing. | |
| 139 | 139 | ||
| 140 | 140 | Variables are set using `:=` operator. For example, to compute the actual target path, one can write the following: | |
| 141 | 141 | ||
| 142 | 142 | `prefix := $(shell cat prefix) # retrieve the content of the file called "prefix"`\ | |
| 143 | 143 | `TARGET_DIR = $(DESTDIR)$(prefix)` | |
| 144 | 144 | ||
| 145 | 145 | When building locally, *DESTDIR* will be empty so that the target path will be the same as *prefix*. When building the package though, *DESTDIR* will indicate a temporary folder to use. | |
| 146 | 146 | ||
| 147 | 147 | To make things easier to update, let's define the name of your project (without the .lpi extension): | |
| 148 | 148 | ||
| 149 | 149 | `PROJECT_NAME := myproject` | |
| 150 | 150 | ||
| 151 | 151 | ##### Compiling | |
| 152 | 152 | ||
| 153 | 153 | After the initialization of variables, the Makefile consists of entries called rules. The syntax of a rule is the following: | |
| 154 | 154 | ||
| 155 | 155 | `rule1: require1 require2`\ | |
| 156 | 156 | `#... how to make it` | |
| 157 | 157 | ||
| 158 | 158 | Here the name of the rule is *rule1* and it requires the rules *require1* and *require2* to be already made. This means that first *require1* and *require2* will be made and only afterwards *rule1* will be made. The following lines contain the instructions to execute to make *rule1*. | |
| 159 | 159 | ||
| 160 | 160 | If a rule does not need any other, there won't be anything after the colon. In the case of a Lazarus project, one can simply write: | |
| 161 | 161 | ||
| 162 | 162 | `all:`\ | |
| 163 | 163 | ` lazbuild --build-mode=Release $(PROJECT_NAME)/$(PROJECT_NAME).lpi` | |
| 164 | 164 | ||
| 165 | 165 | The rule *all* is the one invoked to compile the program. Note that before the instructions, a tab character is needed (not spaces). It is recommended to specify the build-mode, because there may be various build modes like Debug or for different widgetsets (gtk2, gtk3, qt4, qt5). So whatever build mode is active in the project, you will be assured of the build mode used to generate the Debian package. | |
| 166 | 166 | ||
| 167 | 167 | To clean the compiled files, there is a need for another rule: | |
| 168 | 168 | ||
| 169 | 169 | `clean:`\ | |
| 170 | 170 | ` rm -f $(PROJECT_NAME)/$(PROJECT_NAME) # remove generated executable file`\ | |
| 171 | 171 | ` rm -rf lib # remove object files` | |
| 172 | 172 | ||
| 173 | 173 | Note that the object files may be in another folder. Check the project options. | |
| 174 | 174 | ||
| 175 | 175 | For completeness, let's provide a rule to clean the whole building process: | |
| 176 | 176 | ||
| 177 | 177 | `distclean: clean clean_configure`\ | |
| 178 | 178 | `clean_configure:`\ | |
| 179 | 179 | ` rm -f prefix # remove the "prefix" file generated by "configure" script` | |
| 180 | 180 | ||
| 181 | 181 | ##### Installation and package building | |
| 182 | 182 | ||
| 183 | 183 | The `Makefile` needs to be able to install files on the system or to put them in the package. Both will be done with the same code and when building a package, the target directory will instead be a temporary one. | |
| 184 | 184 | ||
| 185 | 185 | We will need additional folders for the installation. | |
| 186 | 186 | ||
| 187 | 187 | `BIN_DIR = $(TARGET_DIR)/bin # executable file`\ | |
| 188 | 188 | `SHARE_DIR = $(TARGET_DIR)/share # other files`\ | |
| 189 | 189 | `RESOURCE_DIR = $(SHARE_DIR)/$(PROJECT_NAME) # custom resources`\ | |
| 190 | 190 | `MANUAL_DIR = $(SHARE_DIR)/man # man page`\ | |
| 191 | 191 | `ICON_DIR = $(SHARE_DIR)/icons/hicolor # icons (multiple resolutions)`\ | |
| 192 | 192 | `PIXMAP_DIR = $(SHARE_DIR)/pixmaps # pixmap (fallback icon)`\ | |
| 193 | - | ||
| 193 | + | ||
| 194 | 194 | `SRC_BIN_DIR = $(PROJECT_NAME)`\ | |
| 195 | 195 | `SRC_INFO_DIR = info`\ | |
| 196 | 196 | `SRC_ICON_DIR = $(SRC_INFO_DIR)/icons` | |
| 197 | 197 | ||
| 198 | 198 | One can retrieve all icons in the folder with: | |
| 199 | 199 | ||
| 200 | 200 | `SRC_ICONS = $(shell find "$(SRC_ICON_DIR)" -maxdepth 1 -type f -name *x*.png -exec basename {} .png ';')` | |
| 201 | 201 | ||
| 202 | 202 | ##### Installation rule | |
| 203 | 203 | ||
| 204 | 204 | The installation will require the *prefix* file to exist. This can be specified like any other rule: | |
| 205 | 205 | ||
| 206 | 206 | `install: prefix`\ | |
| 207 | 207 | ` install -D "$(SRC_BIN_DIR)/$(PROJECT_NAME)" "$(BIN_DIR)/$(PROJECT_NAME)"`\ | |
| 208 | 208 | ` install -d "$(SHARE_DIR)/man/man1"`\ | |
| 209 | 209 | ` gzip -9 -n -c "$(SRC_INFO_DIR)/man/man1/$(PROJECT_NAME).1" >"$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"`\ | |
| 210 | 210 | ` chmod 0644 "$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"`\ | |
| 211 | 211 | ` install -D "$(SRC_INFO_DIR)/$(PROJECT_NAME).desktop" "$(SHARE_DIR)/applications/$(PROJECT_NAME).desktop"`\ | |
| 212 | 212 | ` install -D --mode=0644 "$(SRC_ICON_DIR)/48x48.png" "$(SHARE_DIR)/pixmaps/$(PROJECT_NAME).png"`\ | |
| 213 | 213 | ` for s in $(SRC_ICONS); do install -D --mode=0644 "$(SRC_ICON_DIR)/$$s.png" "$(ICON_DIR)/$$s/apps/$(PROJECT_NAME).png"; done` | |
| 214 | 214 | ||
| 215 | 215 | Note: | |
| 216 | 216 | ||
| 217 | 217 | - copying is done using the `install` command. The -D option will create missing directories for the file and the -d option will create the specified directory. The option --mode=0644 must be used for data files. | |
| 218 | 218 | - the 48x48 icon is used as default pixmap. | |
| 219 | 219 | - there are no resources installed in this case but you can add them in a similar way using `install` command. | |
| 220 | 220 | ||
| 221 | 221 | ##### Uninstallation rule | |
| 222 | 222 | ||
| 223 | 223 | A similar rule must be created to uninstall the software: | |
| 224 | 224 | ||
| 225 | 225 | `uninstall: prefix`\ | |
| 226 | 226 | ` rm -f "$(BIN_DIR)/$(PROJECT_NAME)"`\ | |
| 227 | 227 | ` rm -f "$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"`\ | |
| 228 | 228 | ` rm -f "$(SHARE_DIR)/applications/$(PROJECT_NAME).desktop"`\ | |
| 229 | 229 | ` rm -f "$(SHARE_DIR)/pixmaps/$(PROJECT_NAME).png"`\ | |
| 230 | 230 | ` for s in $(SRC_ICONS); do rm -f "$(ICON_DIR)/$$s/apps/$(PROJECT_NAME).png"; done` | |
| 231 | 231 | ||
| 232 | 232 | ### Compiling upstream | |
| 233 | 233 | ||
| 234 | 234 | Once you have all upstream files ready, you can check it compiles by going into the upstream folder and doing: | |
| 235 | 235 | ||
| 236 | 236 | `./configure`\ | |
| 237 | 237 | `make`\ | |
| 238 | 238 | `sudo make install`\ | |
| 239 | 239 | `#test the program`\ | |
| 240 | 240 | `sudo make uninstall` | |
| 241 | 241 | ||
| 242 | 242 | Note that before installing, make sure your program is not already installed on the system. Otherwise you won't be able to check that the installation was successful. | |
| 243 | 243 | ||
| 244 | 244 | To test that the command line is working, simply call your program or check the manual: | |
| 245 | 245 | ||
| 246 | 246 | `myproject`\ | |
| 247 | 247 | `man myproject` | |
| 248 | 248 | ||
| 249 | 249 | To test that the GUI is working, go in the Linux menu and find your program. Check that it is displayed with the appropriate icon. | |
| 250 | 250 | ||
| 251 | 251 | If everything works, the next step is to get your upstream packaged. You can request that someone take care of it by sending an RFP bug request: <https://wiki.debian.org/RFP> | |
| 252 | 252 | ||
| 253 | 253 | If you don't get any answer, you may want to do the packaging yourself. See [[Debian package source]]. | |
| 254 | 254 | ||
| 255 | 255 | --- | |
| 256 | 256 | *From the Free Pascal wiki, page "Debian upstream", as it stood on 2021-12-16 after a change by Dbannon, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 257 | 257 | Category: Deployment | |
| 258 | 258 | Category: Install | |
| 259 | 259 | Category: Linux |