DragonFly On-Line Manual Pages

DEVELOPMENT(7)    DragonFly Miscellaneous Information Manual    DEVELOPMENT(7)

NAME
     development - quick starter for development with the DragonFly codebase

DESCRIPTION
     DragonFly uses the git(1) distributed revision control system.  If it is
     not already on the system, it needs to be installed via dports(7)
     (devel/git).

     The EXAMPLES section gives initial information to get going with
     development on DragonFly.  Please refer to the git(1) manual pages and
     other related documents for further information on git's capabilities and
     how to use them.  The SEE ALSO section below has some links.

     For information on how to build the DragonFly system from source code,
     see build(7).  For information on how to build the LiveCD, LiveDVD or
     thumb drive image, see release(7).

     For a specification of DragonFly's preferred source code style, refer to
     style(9).  An emacs(1) function to switch C-mode to this style (more or
     less) can be found in /usr/share/misc/dragonfly.el.  For vim(1) users, a
     /usr/share/misc/dragonfly.vim is available.

EXAMPLES
     A fresh copy of the repository can be cloned anywhere.  Note that the
     directory to clone into (/usr/src in the following example) must not
     exist, so all previous work in this directory has to be saved and the
     directory be removed prior to cloning.  Also note that while the main
     repository is on crater, it is recommended that one of the DragonFly
     mirrors be used instead.

     Simple setup of the local repository is done using /usr/Makefile:

         cd /usr
         make help               # get brief help
         make src-create         # create the source repository

     Somewhat finer control can be achieved using git(1) directly.  To clone
     the repository and check out the master branch (this will take some
     time):

         cd /usr
         git clone -o crater git://crater.dragonflybsd.org/dragonfly.git src
         cd src

     The repository can be held up to date by pulling frequently (to set up a
     cron(8) job, git(1)'s --git-dir option can be used):

         cd /usr/src
         git pull

     It is not recommended to work directly in the master branch.  To create
     and checkout a working branch:

         git checkout -b work

     To create and checkout a branch of the DragonFly 2.0 release (called
     rel2_0):

         git checkout -b rel2_0 crater/DragonFly_RELEASE_2_0

     Branches can be deleted just as easy:

         git branch -d work

     After changes have been made to a branch, they can be committed:

         git commit -a

     git-commit(1)'s -m and -F options can be used to specify a commit message
     on the command line or read it from a file, respectively.

     Finally, branches can be merged with the (updated) master by using
     rebase:

         git checkout master
         git pull
         git checkout work
         git rebase master

VENDOR IMPORTS
     When importing vendor sources, make sure that you don't import too many
     unnecessary sources.  Especially test suites that are not used by the
     DragonFly build are good candidates for being stripped away.  These
     instructions assume that you have already extracted the source package
     into its final directory and trimmed the source files appropriately.

     Do not change the vendor sources before importing them on the vendor
     branch!  Necessary changes to the vendor sources should be applied to the
     master branch after the import.

     For the following example, we will import the imaginary package foo-2.3
     into contrib/foo.  If this is the first import of foo, you will have to
     choose the name of the vendor branch.  Customarily, this will be
     vendor/FOO.  However, if you intend to maintain multiple vendor sources
     for the same package concurrently, you should choose a branch name that
     includes part of the version, e.g., vendor/FOO2.

     First, we need to create an orphan branch (i.e., a new branch with no
     history) as the vendor branch:

         git checkout --orphan vendor/FOO

     Then we remove the previous content because the vendor branch will only
     contain the vendor sources to be imported:

         git rm -rf .

     Next, move the prepared vendor sources to the destination, i.e.,
     contrib/foo.  Then we perform the import:

         git add contrib/foo
         git commit -m "Import foo-2.3 on the vendor branch"

     Next, we merge the vendor branch into master:

         git checkout master
         git merge --allow-unrelated-histories vendor/FOO

     Now you are free to change the sources in contrib/foo, since you are back
     to the master branch.  The first thing to do is to add README.DRAGONFLY
     and README.DELETED.  The former documents how the imported sources can be
     obtained, including basic information (e.g., version, date, checksum) of
     the source package.  The latter lists all files and directories that have
     been removed from the source package.  You should use the
     /usr/src/tools/tools/genreadmedeleted/genreadmedeleted shell script to
     generate this file.  Commit the READMEs first:

         git add contrib/foo/README.D*
         git commit -m "foo: add our READMEs"

     And then commit your local changes to the sources.  Finally, push master
     and the vendor branch to the upstream:

         git push crater master vendor/FOO

SEE ALSO
     git(1) (devel/git), build(7), committer(7), release(7)

     Documentation on git's page, http://git-scm.com/documentation.

     Git Magic, http://www-cs-students.stanford.edu/~blynn/gitmagic/.

HISTORY
     The development manual page was originally written by Matthew Dillon
     <dillon@FreeBSD.org> and first appeared in FreeBSD 5.0, December 2002.
     It was rewritten when DragonFly switched to git(1).

DragonFly 5.9-DEVELOPMENT        March 3, 2020       DragonFly 5.9-DEVELOPMENT