Developer Documentation
Grace Past edited this page 2 years ago

Introduction

Most users do not need to build avideo and can download the builds or get them from their distribution.

To run avideo as a developer, you don't need to build anything either. Simply execute

python -m avideo

To run the test, simply invoke your favorite test runner, or execute a test file directly; any of the following work:

python -m unittest discover
python test/test_download.py
nosetests

If you want to create a build of avideo yourself, you'll need

  • python
  • make (only GNU make is supported)
  • pandoc
  • zip
  • nosetests

Hacking on AVideo

AVideo consists of a set of patches to be applied to youtube-dl, stored in a Git repository at NotABug. The 'master' copy of these is stored in the master branch, with a branch for each current release containing a release-specific copy and a tarball of the youtube-dl base source code for that release. Finally, the actual releases are stored in the archive branch. Releases for avideo are made once a month. These consist of a copy of the master branch and a 'freeze'- a tarball containing the then current youtube-dl source. They are initially published as a beta, before being declared stable after one month or no serious issues are apparent, whichever is later.

As a hacker, you will probably want to fork the branch(es) for the release(s) of interest to you, as well as perhaps master if you believe your patches will also apply to future avideo versions. These can then be pulled, edits and commits made, and then pushed and merged. Also see series.sh.

The AVideo Code Layout

AVideo consists of a set of patches, applied to the youtube-dl source code at release time to produce the software which is published. These patches come in two main forms:

  • Whole File: entire files which are added, removed, or replaced.
  • Code: patches which replace a small section of text in a file with a different small section, independently of changes made to other parts of that file.

The method by which these patches are applied involves further subclassification, as performed below. However, it is essential to note that the all changes made to a freeze are contained in the patches applied (and the software used to apply those patches): changes made directly to the source code of a release are not permanent. They can be used for testing, but should be incorporated as a patch before pushing or publishing. With that in mind, the patching process is as follows:

Deletion

Any whole files that are to be deleted or replaced are first removed. Which files are up for the chop is set in 'Patches/ban.txt'. In order to change or amend this, simply list the files one to a line, ensuring no empty lines.

Addition

After deletion, new files and the replacements for replaced files are added. The files to be added are copied exactly from 'Patches/Files/', preserving directory structure and metadata. Be aware that empty directories will not copy, though- an empty dotfile can be used to circumvent this.

Permanent Patches

Code patches are then applied. The first set of such patches to be added are the 'permanent patches': those which are considered permanent enough for the master branch. All permanent patches are stored in 'Patches/Perm'. For a description of the patch format, see AVideo Patching System.

Bug Patches

After permanent patches, bug patches are applied. These are also code patches, but are only intended for one or two particular releases- making them bug patches. Bug patches are stored in 'Patches/Bug'. They use the same patch format as permanent patches, documented at AVideo Patching System.

Branding Patches

The final code patches to be applied are branding patches. These have a very specific purpose: to prevent certain appearances of the phrase 'youtube-dl' or 'youtube_dl' being replaced with 'avideo' as part of rebranding. Branding patches are listed in 'Patches/namae.txt'. All those intended to apply to a given file are arranged into a paragraph, consisting of the (relative), followed by a colon, at the top, and the lines with instances of the name to be protected placed one to a line beneath it. The paragraphs are then separated from one another by a single blank line.

Rebranding

Finally, the software is rebranded. This involves replacing references to youtube-dl with ones to avideo, including URLs. The list of changes made is contained in the source file 'func.py'. In general, all references not to a specific issue on their website will be replaced. To protect a specific reference, use a branding patch or replace it with youtu`be-dl.

AVideo Patching System

Permanent and bug patches use a specific, avideo-exclusive format.

Patch files, possessing a name not starting with 'g', consist of three parts. The first line begins with a #, followed by the (relative) path of the file to which it applies, followed by a colon, and concluding with a brief description of the patch's purpose.

The second line begins with "#ln=". This, an assignment to the 'linker'- text intended to replace what is being replace- can then be made in one of two ways:

  • If followed by the empty string (i.e. nothing), the linker is read from the file in the same directory named 'g' followed by the name of the patch file. It reads it verbatim, beginning at the second line of the file; the first line is left for a comment, which we recommend making in the same format as the patch file's first line.
  • Otherwise, the linker is read as the text following the = sign. No quotes of any form are used, and there are just three escape sequences. \n is a newline, \t is a tab, and \z is the 'null character'. The null character can be used when the linker is an empty string, to prevent it from trying to be read from a file, or in between the \ and letter of an escape sequence to stop it being expanded.

Finally, the remainder of the file is the text to be replaced by the linker. It is important to note that this will be replaced wherever it occurs in the file.

Series Shell File

The series.sh file, found in the root of each series and the master branch, is a key component of using avideo. It offers several commands for managing releases. As a hacker, the ones you will need are 'build' and 'clean'.

Build

The command './series.sh build' applies a set of patches to the freeze, producing a directory 'avideo' containing the source for a release. Cding into this, the makefile offers various different commands to build from this- 'make pub' manufactures the set of binaries, for example.

Clean

The command './series.sh clean' will remove the materials created in building, cleaning the directory.