{"id":27954399,"url":"https://github.com/breezy-team/breezy-debian","last_synced_at":"2025-05-07T17:28:21.149Z","repository":{"id":44155855,"uuid":"134069833","full_name":"breezy-team/breezy-debian","owner":"breezy-team","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-02T15:38:33.000Z","size":16937,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T16:41:46.638Z","etag":null,"topics":["breezy","brz","bzr","debian"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/breezy-team.png","metadata":{"files":{"readme":"README.rst","changelog":"changelog.py","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-19T14:35:47.000Z","updated_at":"2025-04-02T15:38:31.000Z","dependencies_parsed_at":"2025-02-10T21:21:13.430Z","dependency_job_id":"4e16fc3e-1fdb-4c9f-a920-d4f232b3de2d","html_url":"https://github.com/breezy-team/breezy-debian","commit_stats":null,"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezy-team%2Fbreezy-debian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezy-team%2Fbreezy-debian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezy-team%2Fbreezy-debian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/breezy-team%2Fbreezy-debian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/breezy-team","download_url":"https://codeload.github.com/breezy-team/breezy-debian/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252925715,"owners_count":21826203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["breezy","brz","bzr","debian"],"created_at":"2025-05-07T17:28:20.148Z","updated_at":"2025-05-07T17:28:21.142Z","avatar_url":"https://github.com/breezy-team.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"brz-debian\n==========\n\nOverview\n--------\n\nThis is brz-debian, a plugin for `Breezy`_ that allows you to build `Debian`_\npackages from a Breezy compatible branch, like a Git repository or a Bazaar\nbranch.\n\n.. _Breezy: https://www.breezy-vcs.org/\n.. _Debian: http://www.debian.org/\n\nNote that there is a user manual available at\n/usr/share/doc/brz-debian/user_manual/index.html that gives more\ninformation than this file.\n\nInstallation\n------------\n\nThis plugin requires `python-debian`_ and Breezy.\n\n.. _python-debian: http://bzr.debian.org/pkg-python-debian/trunk/\n\nIt also requires the ``dpkg-dev`` package to be installed (for the\n``dpkg-mergechangelogs`` tool)::\n\n  apt install dpkg-dev\n\nThis plugin can be installed in two ways. As you are probably using a Debian\nsystem you can probably just use the Debian packages. The other way is to\nbranch it in to ``~/.breezy/plugins/debian``, i.e::\n\n  brz branch https://code.breezy-vcs.org/breezy-debian/trunk/ \\\n    ~/.config/breezy/plugins/debian\n\nThis will give you a ``brz builddeb`` command (alias ``bd``).\n\nHelp for this plugin can be found by running ``brz help builddeb``.\n\nThere is also a script named ``brz-buildpackage`` provided in /usr/bin\nthat provides access to the tool as well. It is just a wrapper script that\ncalls ``brz builddeb`` with the arguments you provide, so the rest of the\ndocumentation applies equally well to using this script. Probably the only\ndifference is that help will be got with ``brz-buildpackage ---help``\n(as ``brz builddeb --help`` also works and does the same as\n``brz help builddeb``). The script is provided for two reasons, the first\nis similarity to the other ``-buildpackage`` systems, and the second is so\nthat the Debian package can provide the ``brz-buildpackage`` package, and\nso make it easier for people to find the package.\n\nConfiguration\n-------------\n\nThere are also configuration files that can be used, these are, in the order\nthat values will be used if found::\n\n  * .bzr-builddeb/local.conf (in the package directory)\n  * ~/.bazaar/builddeb.conf\n  * .bzr-builddeb/default.conf (in the package directory)\n\nThe last of these should be used for values that will be used by all users of\nthe package, for instance 'merge = True'. The others are for the user to add\nor override settings that are specific to them, either globally or per package.\n\nThere is one complication to this however. As arbitrary commands can be\nspecified for some of the options there is a potential security hole. This\nis closed by only taking these options from the configuration file in your\nhome directory, which can't be changed by another committer to the branch.\nI apologise if this breaks your setup, and if you can't work around it please\ntalk to me to try to find an approach that satisfies you and does not open\nany security holes.\n\nThese files must start with::\n\n  [BUILDDEB]\n\nConfiguration Options\n~~~~~~~~~~~~~~~~~~~~~\n\nThe following options are read from the configuration files. Most can also be\nused as command line arguments by prepending ``--`` to the names and not using\nthe ``\\=`` symbol. There are a few exceptions to this that are noted in the\ndescriptions.\n\nDirectories\n###########\n\nThese change the directories that the plugin uses for various things.\n\n  * ``build-dir = path``\n\n    The directory in which the build takes place. (Defaults to\n    ``../build-area`` relative to the branch).\n\n  * ``result-dir = path``\n\n    The directory the resulting files will be placed in. (Defaults to ``..``)\n\n  * ``orig-dir = path``\n\n    The directory to search for the ``.orig.tar.gz`` when not in native mode.\n    (Defaults to ``..`` relative to the branch).\n\nModes\n#####\n\nThese change the way in which the plugin operates. They can be set depending\non the type of package you are building.\n\n  * ``merge = True``\n\n    Turns on merge mode. This is where only the ``debian/`` directory is\n    versioned. It uses and ``orig.tar.gz`` for the upstream and combines the\n    two before building. It works with both the ``debian/`` directory in the\n    branch, or the contents of ``debian/`` (e.g. ``rules``, ``control``)\n    directly in the top level directory of the branch. (Defaults to ``False``).\n\n  * ``native = True``\n\n    If you want to build a native package from a branch then turn on this\n    option. It will stop the plugin from looking for an ``orig.tar.gz`` and\n    build a native package instead. This has no effect if merge mode is on,\n    as I don't think it makes any sense to version the ``debian/`` separately\n    for a native package. If you disagree let me know.\n\n  * ``split = True``\n\n    This takes a package from a branch that includes both the upstream source\n    and the ``debian/`` dir and creates a non-native package from it by\n    creating an ``orig.tar.gz`` from the code outside of ``debian/``. This\n    is probably most useful if you are bot upstream and Debian maintainer\n    of a non-native package. This has no effect if ``merge`` or ``native``\n    are true, the former is for use when you don't version the full source,\n    the second for when you don't need an ``orig.tar.gz`` so they make no sense\n    to be used together.\n\n  * ``export-upstream = path``\n\n    This option takes a path (remote or local) to a brz branch that contains\n    the upstream code. If this is set then the plugin will export the code\n    from that branch to create the ``.orig.tar.gz``. This option only has any\n    effect if ``merge`` is set.\n\n  * ``export-upstream-revision = revision``\n\n    This sets the revision that the upstream code will be branched at. It takes\n    the same revision spec as the normal --revision parameter. Use it to\n    associate an upstream version number with a particular revision of the\n    upstream code. This has no effect if ``export-upstream`` is not set.\n\nBuilders\n########\n\nThese configure the commands that are used to build the package in different\nsituations.\n\n  * ``builder = command``\n\n    The command to use to build the package. Defaults to ``debuild``).\n    Will only be read from the file in your home directory.\n\n  * ``quick-builder = command``\n\n    The command used to build the package if the ``--quick`` option is used.\n    (Defaults to ``fakeroot debian/rules binary``). Will only be read from\n    the file in your home directory.\n\nThe idea is that certain options can be set in ``.bzr-builddeb/default.conf``\nthat apply to the package on all systems, or that there is a default that is\nwanted that differs from the default provided. ``merge = True`` is a perfect\nexample of this.\n\nThen the user can override this locally if they want for all of their packages\n(they prefer ``builder = pdebuild``), so they can set this in\n``~/.bazaar/builddeb.conf``. They can override it for the package if they want\n(e.g. they have a different location for upstream tarballs of a package if\nthey are involved with upstream as well, so they set ``orig_dir =\n/home/.../releases/``), this can be done in ``.bzr-builddeb/local.conf``).\n\nCreating a package\n------------------\n\nBelow are instructions for creating a package. These instructions differ\ndepending on whether you want to use merge mode or not.\n\nFirst the common start create a directory to hold your work. This is not\nabsolutely necessary, but as you still get all the power of brz when using\nthis plugin, so you might want to branch etc. and so this will be useful\nlater on::\n\n  $ mkdir path/to/project\n\nIf you are going to be using branches then the following is a good optimisation\nyou can use::\n\n  $ brz init-repo --trees path/to/project\n\nNow create your global config file if you want to change something like the\nbuilder in use, or have a global result directory or similar::\n\n  $ echo \"[BUILDDEB]\" \u003e ~/.bazaar/builddeb.conf\n  $ $EDITOR ~/.bazaar/builddeb.conf\n\nand any options that you want.\n\nI will describe creating a new project, but for existing projects you can\ncopy the code over and call ``brz init`` then continue in the same way.\n\nI will also describe the setup that conforms to the default options for\ndirectories. If you wish to use a different layout set up the options to\nyour liking and tweak the commands below as necessary.\n\nUsing merge mode\n~~~~~~~~~~~~~~~~\n\nMerge mode is when only the ``debian/`` directory of the package is versioned,\nwith the upstream version of the code living elsewhere. It allows for clear\nseparation of the Debian specific changes from the upstream code.\n\nFirst copy the ``.orig.tar.gz`` file for the current version in to the parent\ndirectory. If you do not have the upstream tarball for the current version,\nbut you do have a ``watch`` file detailing where it can be found then the\nplugin will automatically retrieve the tarballs as they are needed.\n\nNow create the branch for the ``debian/`` directory::\n\n  $ brz init project\n\nNow you can either create a ``project/debian/`` directory for all the files,\nor add them in the ``project`` directory.\n\nNow tell bzr-builddeb that this is a merge mode project::\n\n  $ cd project/\n  $ mkdir .bzr-builddeb/\n  $ echo -e \"[BUILDDEB]\\nmerge = True\" \u003e .bzr-builddeb/default.conf\n\nNow you are ready to create the project. Create the usual files, and edit them\nto your satisfaction. When you have the files run::\n\n  $ brz add\n  $ brz ci\n\nfrom the root of the project branch.\n\nYou are now ready to build the project. See below for instructions on doing\nthis.\n\nNon-merge mode\n~~~~~~~~~~~~~~\n\nThis is a little simpler to set up. Create the branch for the project::\n\n  $ cd path/to/project\n  $ brz init project\n\nNow add all the project files to the branch, and add the to bzr::\n\n  $ cd project\n  $ brz add\n  $ brz ci\n\nThere are two options when you want to build a Debian package, whether\nit is a native package or not. Most packages are non-native so I will describe\nthat first.\n\nTo create a non-native package you need an upstream tarball to build against.\nSet the ``orig-dir`` variable to the directory containing the tarball that\nyou want to use and the plugin will pick it up and you will have a non-native\npackage. If you do not have the upstream tarball corresponding to the version\nof the package you are trying to build, but you have a ``watch`` file\ndetailing where it can be found then it will be automatically retrieved when\nneeded.\n\nHowever sometimes you might be upstream of a package as well as Debian\nmaintainer, but it is not a native package. In that case you may version\nthe whole source including ``debian/``, but not want to have to manually\nmake a tarball without the ``debian/`` directory. In that case see the\n``split`` variable. If you set that then the plugin will create you an\nappropriately named orig.tar.gz of everything outside of ``debian/``.\n\nIf you want to have a native package you don't need to worry about\n``orig-dir``, but instead set ``native = True`` in the\n``.bzr-builddeb/default.conf`` file (make sure it starts with ``[BUILDDEB]``\nif you create it).\n\nNow you are ready to build using the plugin.\n\nBuilding a Package\n------------------\n\nOnce your package is set up then building it is easy. Run the following\ncommand from the top-level of the project branch, after checking in all\nchanges::\n\n  $ brz bd\n\nIf you used the default options this should build the package and leave the\nresulting files in ``../build-area``.\n\nNote that most of the options can be used as parameters to this command as well\nby prefixing their name with ``--``. So you can do for example::\n\n  $ brz bd --builder pdebuild\n\nto change from what is in the configuration files. Note that there is currently\nno way to set the binary options to false if they are set to true in the\nconfiguration files. It would be possible to allow this, but it would bloat\nthe code and the help listings quite a lot, so I will only it if asked to.\n\nTips\n----\n\nIf you have a slow builder defined in your configuration (for instance\n``pdebuild``, you can bypass this by using the ``--quick`` option. This uses\nwhatever the ``quick_builder`` option is (defaults to ``fakeroot debian/rules\nbinary``).\n\nIf you are running in merge mode, and you have a large upstream tarball, and\nyou do not want to unpack it at every build you can speed things up even more.\nThis involves reusing the tarball each build, so saving the need to unpack it.\nTo do this run::\n\n  $ brz bd --export-only\n\nonce to create a build-dir to use. (``-e`` is the short option for this). Then\non the next builds you can use the ``--reuse`` and ``--dont-purge`` options to\nkeep using this build directory. **N.B. This may cause build problems,\nespecially if files are removed**, it is advisable to run a build without\n``--reuse`` after removing any files.\n\nWorkflow\n--------\n\nbrz-debian is designed to fit in with the workflow that brz encourages. It\nis designed as a plugin, so that it just becomes one more ``brz`` command that\nyou run while working on the package.\n\nIt also works fine with the frequent branching approach of brz, so that you\ncan branch to test something new for the package, or for a bug fix, and then\nmerge it back in to your main branch when it is done.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreezy-team%2Fbreezy-debian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbreezy-team%2Fbreezy-debian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbreezy-team%2Fbreezy-debian/lists"}