Sign in Join
Wiki copytemporary

Debian upstream: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

OldNewLine
11On 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.
22
33If you want to distribute the .deb file directly, you may generate it following [[Debian package structure]].
44
55### Dependence on Lazarus custom packages
66
77Generally 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).
88
99If 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.
1010
1111Publishing 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.
1212
1313### Upstream source, package maintainer and sponsor
1414
1515There are different levels when it comes to uploading packages into Debian:
1616
1717- upstream source provided by the software developer
1818- [[Debian package source]] provided by the package maintainer
1919- upload done by the package sponsor/mentor
2020
2121Note 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.
2222
2323The term sponsor/mentor does not refer to a financial support but to a Debian developer.
2424
2525### Upstream source content
2626
2727The upstream source consists of:
2828
2929- you project source code and custom Lazarus packages source code
3030- compilation scripts
3131- additional information about the program
3232
3333It can be organized for example like this:
3434
35-`upstream`\
36-`  ├─ myproject ...     # folder for main project (containing a .lpi file)`\
37-`  ├─ custompackage ... # folder for custom package (containing a .lpk file)`\
38-`  ├─ configure         # script to setup compilation`\
39-`  ├─ Makefile          # compilation and installation script`\
40-`  └─ info`\
41-`      ├─ myproject.1         # command line manual`\
42-`      ├─ myproject.desktop   # GUI application description`\
43-`      └─ icons               # GUI icons`\
44-`          ├─ 16x16.png`\
45-`          ├─ 32x32.png`\
46-`          ...`
35+```text
36+upstream
37+ ├─ myproject ... # folder for main project (containing a .lpi file)
38+ ├─ custompackage ... # folder for custom package (containing a .lpk file)
39+ ├─ configure # script to setup compilation
40+ ├─ Makefile # compilation and installation script
41+ └─ info
42+ ├─ myproject.1 # command line manual
43+ ├─ myproject.desktop # GUI application description
44+ └─ icons # GUI icons
45+ ├─ 16x16.png
46+ ├─ 32x32.png
47+ ...
48+```
4749
4850In 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.
4951
5052Common 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.
5153
5254#### Project and custom packages
5355
5456It 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`.
5557
5658#### Command line manual
5759
5860The syntax is of the .1 file is a bit peculiar. There are some tools to help but you still need to know the syntax.
5961
6062- description of the syntax: <https://liw.fi/manpages/>
6163- editor with wizard and WYSIWYG preview mode: **gmanedit**
6264- live preview editor (toggle to **AN mode**): <https://roperzh.github.io/grapse/>
6365
6466Here is a sample file:
6567
66-`.TH Project1 1 "19 May 2020" "" Project1`\
67-`.SH NAME`\
68-`Project1 - My cool project`\
69-`.SH SYNOPSIS`\
70-`.B project1`\
71-`[PARAMETER]`\
72-`.SH DESCRIPTION`\
73-`What my program does.`\
74-`.PP`\
75-`More description.`
68+``` pascal
69+.TH Project1 1 "19 May 2020" "" Project1
70+.SH NAME
71+Project1 - My cool project
72+.SH SYNOPSIS
73+.B project1
74+[PARAMETER]
75+.SH DESCRIPTION
76+What my program does.
77+.PP
78+More description.
79+```
7680
7781#### Application description
7882
7983To add your application to the Linux menu, you need to add a file called ***.desktop** containing:
8084
81-`[Desktop Entry]`\
82-`Name=Project1`\
83-`Comment=Cool project`\
84-`Icon=project1`\
85-`Exec=project1`\
86-`Terminal=false`\
87-`Type=Application`\
88-`Categories=Graphics`\
89-`GenericName=Project1`\
90-`Keywords=feature1; feature2; feature3`
85+``` pascal
86+[Desktop Entry]
87+Name=Project1
88+Comment=Cool project
89+Icon=project1
90+Exec=project1
91+Terminal=false
92+Type=Application
93+Categories=Graphics
94+GenericName=Project1
95+Keywords=feature1; feature2; feature3
96+```
9197
9298This file is similar to a shortcut to your program.
9399
94100The **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.
95101
96102The keywords help search through applications.
97103
98104#### configure script
99105
100106The 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`.
101107
102-`#!/bin/bash`\
103-`args=("$@")`\
104-`defaultprefix=/usr/local`\
105-`wantedprefix=$defaultprefix`\
106-`for param in "${args[@]}"`\
107-`do`\
108-`   if [ "$param" == "-h" ] || [ "$param" == "--help" ]; then`\
109-`       echo "Usage: ./configure [OPTIONS]"`\
110-`       echo ""`\
111-`       echo "    --prefix=PREFIX"`\
112-`       echo "        Specifies the install prefix."`\
113-`       echo "        By default prefix is \"$defaultprefix\"" `\
114-`       echo "        For packages use \"/usr\""`\
115-`       exit 0`\
116-`   elif [ "${param:0:9}" == "--prefix=" ]; then`\
117-`       wantedprefix=${param:9}`\
118-`   else`\
119-`       echo "Warning: unknown option $param"`\
120-`   fi`\
121-`done`\
122-`echo "Prefix set to: $wantedprefix"`\
123-`echo $wantedprefix >prefix  # store the prefix into the file called "prefix"`
108+```text
109+#!/bin/bash
110+args=("$@")
111+defaultprefix=/usr/local
112+wantedprefix=$defaultprefix
113+for param in "${args[@]}"
114+do
115+ if [ "$param" == "-h" ] || [ "$param" == "--help" ]; then
116+ echo "Usage: ./configure [OPTIONS]"
117+ echo ""
118+ echo " --prefix=PREFIX"
119+ echo " Specifies the install prefix."
120+ echo " By default prefix is \"$defaultprefix\""
121+ echo " For packages use \"/usr\""
122+ exit 0
123+ elif [ "${param:0:9}" == "--prefix=" ]; then
124+ wantedprefix=${param:9}
125+ else
126+ echo "Warning: unknown option $param"
127+ fi
128+done
129+echo "Prefix set to: $wantedprefix"
130+echo $wantedprefix >prefix # store the prefix into the file called "prefix"
131+```
124132
125133Here are examples of calls:
126134
127-`./configure                 # when testing the program locally`\
128-`./configure --prefix=/usr   # when building the package`
135+``` pascal
136+./configure # when testing the program locally
137+./configure --prefix=/usr # when building the package
138+```
129139
130140#### Makefile
131141
132142##### Initialization
133143
134144The 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:
135145
136-`SHELL := /bin/bash`
146+``` pascal
147+SHELL := /bin/bash
148+```
137149
138150Note 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.
139151
140152Variables are set using `:=` operator. For example, to compute the actual target path, one can write the following:
141153
142-`prefix := $(shell cat prefix)   # retrieve the content of the file called "prefix"`\
143-`TARGET_DIR = $(DESTDIR)$(prefix)`
154+``` pascal
155+prefix := $(shell cat prefix) # retrieve the content of the file called "prefix"
156+TARGET_DIR = $(DESTDIR)$(prefix)
157+```
144158
145159When 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.
146160
147161To make things easier to update, let's define the name of your project (without the .lpi extension):
148162
149-`PROJECT_NAME := myproject`
163+``` pascal
164+PROJECT_NAME := myproject
165+```
150166
151167##### Compiling
152168
153169After the initialization of variables, the Makefile consists of entries called rules. The syntax of a rule is the following:
154170
155-`rule1: require1 require2`\
156-`#... how to make it`
171+```text
172+rule1: require1 require2
173+#... how to make it
174+```
157175
158176Here 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*.
159177
160178If 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:
161179
162-`all:`\
163-`   lazbuild --build-mode=Release $(PROJECT_NAME)/$(PROJECT_NAME).lpi`
180+```text
181+all:
182+ lazbuild --build-mode=Release $(PROJECT_NAME)/$(PROJECT_NAME).lpi
183+```
164184
165185The 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.
166186
167187To clean the compiled files, there is a need for another rule:
168188
169-`clean:`\
170-`   rm -f $(PROJECT_NAME)/$(PROJECT_NAME)  # remove generated executable file`\
171-`   rm -rf lib             # remove object files`
189+``` pascal
190+clean:
191+ rm -f $(PROJECT_NAME)/$(PROJECT_NAME) # remove generated executable file
192+ rm -rf lib # remove object files
193+```
172194
173195Note that the object files may be in another folder. Check the project options.
174196
175197For completeness, let's provide a rule to clean the whole building process:
176198
177-`distclean: clean clean_configure`\
178-`clean_configure:`\
179-`   rm -f prefix     # remove the "prefix" file generated by "configure" script`
199+```text
200+distclean: clean clean_configure
201+clean_configure:
202+ rm -f prefix # remove the "prefix" file generated by "configure" script
203+```
180204
181205##### Installation and package building
182206
183207The `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.
184208
185209We will need additional folders for the installation.
186210
187-`BIN_DIR = $(TARGET_DIR)/bin                  # executable file`\
188-`SHARE_DIR = $(TARGET_DIR)/share              # other files`\
189-`RESOURCE_DIR = $(SHARE_DIR)/$(PROJECT_NAME)  # custom resources`\
190-`MANUAL_DIR = $(SHARE_DIR)/man                # man page`\
191-`ICON_DIR = $(SHARE_DIR)/icons/hicolor        # icons (multiple resolutions)`\
192-`PIXMAP_DIR = $(SHARE_DIR)/pixmaps            # pixmap (fallback icon)`\
211+```text
212+BIN_DIR = $(TARGET_DIR)/bin # executable file
213+SHARE_DIR = $(TARGET_DIR)/share # other files
214+RESOURCE_DIR = $(SHARE_DIR)/$(PROJECT_NAME) # custom resources
215+MANUAL_DIR = $(SHARE_DIR)/man # man page
216+ICON_DIR = $(SHARE_DIR)/icons/hicolor # icons (multiple resolutions)
217+PIXMAP_DIR = $(SHARE_DIR)/pixmaps # pixmap (fallback icon)
193218
194-`SRC_BIN_DIR = $(PROJECT_NAME)`\
195-`SRC_INFO_DIR = info`\
196-`SRC_ICON_DIR = $(SRC_INFO_DIR)/icons`
219+SRC_BIN_DIR = $(PROJECT_NAME)
220+SRC_INFO_DIR = info
221+SRC_ICON_DIR = $(SRC_INFO_DIR)/icons
222+```
197223
198224One can retrieve all icons in the folder with:
199225
200-`SRC_ICONS = $(shell find "$(SRC_ICON_DIR)" -maxdepth 1 -type f -name *x*.png -exec basename {} .png ';')`
226+``` pascal
227+SRC_ICONS = $(shell find "$(SRC_ICON_DIR)" -maxdepth 1 -type f -name *x*.png -exec basename {} .png ';')
228+```
201229
202230##### Installation rule
203231
204232The installation will require the *prefix* file to exist. This can be specified like any other rule:
205233
206-`install: prefix`\
207-`   install -D "$(SRC_BIN_DIR)/$(PROJECT_NAME)" "$(BIN_DIR)/$(PROJECT_NAME)"`\
208-`   install -d "$(SHARE_DIR)/man/man1"`\
209-`   gzip -9 -n -c "$(SRC_INFO_DIR)/man/man1/$(PROJECT_NAME).1" >"$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"`\
210-`   chmod 0644 "$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"`\
211-`   install -D "$(SRC_INFO_DIR)/$(PROJECT_NAME).desktop" "$(SHARE_DIR)/applications/$(PROJECT_NAME).desktop"`\
212-`   install -D --mode=0644 "$(SRC_ICON_DIR)/48x48.png" "$(SHARE_DIR)/pixmaps/$(PROJECT_NAME).png"`\
213-`   for s in $(SRC_ICONS); do install -D --mode=0644 "$(SRC_ICON_DIR)/$$s.png" "$(ICON_DIR)/$$s/apps/$(PROJECT_NAME).png"; done`
234+```text
235+install: prefix
236+ install -D "$(SRC_BIN_DIR)/$(PROJECT_NAME)" "$(BIN_DIR)/$(PROJECT_NAME)"
237+ install -d "$(SHARE_DIR)/man/man1"
238+ gzip -9 -n -c "$(SRC_INFO_DIR)/man/man1/$(PROJECT_NAME).1" >"$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"
239+ chmod 0644 "$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"
240+ install -D "$(SRC_INFO_DIR)/$(PROJECT_NAME).desktop" "$(SHARE_DIR)/applications/$(PROJECT_NAME).desktop"
241+ install -D --mode=0644 "$(SRC_ICON_DIR)/48x48.png" "$(SHARE_DIR)/pixmaps/$(PROJECT_NAME).png"
242+ for s in $(SRC_ICONS); do install -D --mode=0644 "$(SRC_ICON_DIR)/$$s.png" "$(ICON_DIR)/$$s/apps/$(PROJECT_NAME).png"; done
243+```
214244
215245Note:
216246
217247- 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.
218248- the 48x48 icon is used as default pixmap.
219249- there are no resources installed in this case but you can add them in a similar way using `install` command.
220250
221251##### Uninstallation rule
222252
223253A similar rule must be created to uninstall the software:
224254
225-`uninstall: prefix`\
226-`   rm -f "$(BIN_DIR)/$(PROJECT_NAME)"`\
227-`   rm -f "$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"`\
228-`   rm -f "$(SHARE_DIR)/applications/$(PROJECT_NAME).desktop"`\
229-`   rm -f "$(SHARE_DIR)/pixmaps/$(PROJECT_NAME).png"`\
230-`   for s in $(SRC_ICONS); do rm -f "$(ICON_DIR)/$$s/apps/$(PROJECT_NAME).png"; done`
255+```text
256+uninstall: prefix
257+ rm -f "$(BIN_DIR)/$(PROJECT_NAME)"
258+ rm -f "$(SHARE_DIR)/man/man1/$(PROJECT_NAME).1.gz"
259+ rm -f "$(SHARE_DIR)/applications/$(PROJECT_NAME).desktop"
260+ rm -f "$(SHARE_DIR)/pixmaps/$(PROJECT_NAME).png"
261+ for s in $(SRC_ICONS); do rm -f "$(ICON_DIR)/$$s/apps/$(PROJECT_NAME).png"; done
262+```
231263
232264### Compiling upstream
233265
234266Once you have all upstream files ready, you can check it compiles by going into the upstream folder and doing:
235267
236-`./configure`\
237-`make`\
238-`sudo make install`\
239-`#test the program`\
240-`sudo make uninstall`
268+``` pascal
269+./configure
270+make
271+sudo make install
272+#test the program
273+sudo make uninstall
274+```
241275
242276Note 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.
243277
244278To test that the command line is working, simply call your program or check the manual:
245279
246-`myproject`\
247-`man myproject`
280+```text
281+myproject
282+man myproject
283+```
248284
249285To test that the GUI is working, go in the Linux menu and find your program. Check that it is displayed with the appropriate icon.
250286
251287If 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>
252288
253289If you don't get any answer, you may want to do the packaging yourself. See [[Debian package source]].
254290
255291---
256292*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).*
257293Category: Deployment
258294Category: Install
259295Category: Linux

Back to history