debianize 0.163.0

Create Debian packaging from upstream sources
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# Troubleshooting debianize

When `debianize` produces unexpected or incomplete results, these steps can help
you understand what it sees and why it makes the choices it does.

## 1. Enable verbose output

Run debianize with `--verbose` (or `-v`) to get more detailed output about what
it is doing and why:

```sh
debianize --verbose
```

This is the first thing to try when something goes wrong — the extra output
often makes the problem obvious.

## 2. Check what ognibuild detects

Run `ogni info` in the upstream source directory to see what build system and
metadata ognibuild detects:

```sh
ogni info
```

This shows the detected build system, declared dependencies, and other
information that debianize relies on. If this output is wrong or incomplete,
debianize will produce incorrect packaging.

## 3. Check upstream metadata

Run `guess-upstream-metadata` to see what upstream metadata is detected:

```sh
guess-upstream-metadata
```

This reports fields like the project name, homepage, repository URL, bug
tracker, and description. debianize uses this metadata to populate
`debian/control`, `debian/copyright`, `debian/watch`, and other files. Missing
or incorrect metadata here explains missing or wrong fields in the generated
packaging.

You can also pass `--verbose` for more detail on where each field was found:

```sh
guess-upstream-metadata --verbose
```

## 4. Analyse build logs

If a build fails, you can use `analyse-sbuild-log` or `analyse-build-log` to
extract structured information from the build log:

```sh
analyse-sbuild-log < buildlog.txt
analyse-build-log < buildlog.txt
```

`analyse-sbuild-log` is for logs produced by sbuild; `analyse-build-log` is for
plain dpkg-buildpackage or similar logs. These tools parse the log and report
the detected error, missing dependencies, and other actionable information.
This is the same analysis that `--iterate-fix` uses internally, so running it
manually can help you understand why automatic fixing did or did not work.

## 5. Common issues

### Wrong build system detected

If `ogni info` reports the wrong build system, you can force a specific one:

```sh
debianize --buildsystem NAME
```

### Missing dependencies

If the generated `debian/control` is missing build or runtime dependencies,
check whether `ogni info` lists them. If not, the upstream metadata may be
incomplete (e.g. a missing `requirements.txt` or incomplete `Cargo.toml`
dependencies section).

### Metadata fields are wrong or missing

If `guess-upstream-metadata` does not find the correct homepage, description,
or repository URL, the upstream project may be missing standard metadata files
or conventions. You can manually edit the generated `debian/` files after
running debianize.

### Build failures

Use `--iterate-fix` / `-x` to let debianize attempt to automatically fix build
failures:

```sh
debianize --iterate-fix
```

This runs `deb-fix-build` in a loop to resolve common build issues.

## 6. Crashes and bugs

If debianize crashes or produces clearly wrong output, the bug may not be in
debianize itself. debianize builds on a stack of underlying libraries and tools,
and the issue is often in one of them:

- **ognibuild** — build system detection, dependency resolution, and build
  execution
- **upstream-ontologist** — upstream metadata guessing (used by
  `guess-upstream-metadata`)
- **lintian-brush** — Debian packaging fixers (used by `--iterate-fix`)
- **buildlog-consultant** — build log parsing (used by `analyse-build-log`,
  `analyse-sbuild-log`, and `--iterate-fix`)
- **deb822-lossless** — parsing and editing of `debian/control` and other
  Deb822-format files
- **debian-changelog** — parsing and editing of `debian/changelog`
- **debian-watch** — parsing and editing of `debian/watch`

When filing a bug, try to identify which layer is at fault. For example:

- If `guess-upstream-metadata` gives wrong results on its own, file against
  upstream-ontologist.
- If `ogni info` misdetects the build system, file against ognibuild.
- If `analyse-sbuild-log` misparses a build failure, file against
  buildlog-consultant.
- If the generated `debian/control` has syntax errors, the issue may be in
  deb822-lossless.

Including `--verbose` output and, if applicable, the build log in your bug
report makes it much easier to diagnose.