mirror of
https://github.com/silenty4ng/uv-k5-firmware-chinese-lts
synced 2025-02-21 17:35:57 +00:00
362 lines
13 KiB
Text
362 lines
13 KiB
Text
This file describes the development environment for Texinfo.
|
||
|
||
Copyright 2002-2022 Free Software Foundation, Inc.
|
||
|
||
Copying and distribution of this file, with or without modification,
|
||
are permitted in any medium without royalty provided the copyright
|
||
notice and this notice are preserved.
|
||
|
||
The development sources for GNU Texinfo are available through git
|
||
at Savannah:
|
||
https://savannah.gnu.org/git/?group=texinfo
|
||
|
||
This distribution uses whatever versions of Automake, Autoconf, and
|
||
Gettext are listed in NEWS; usually the latest official releases. If
|
||
you are getting the sources from the development repository (or change
|
||
configure.ac), you'll need to have these tools installed to (re)build.
|
||
You'll also need help2man. If you modify texindex/ti.twjr, you'll need
|
||
gawk >= 4.0. All of these programs are available from
|
||
http://ftp.gnu.org/gnu.
|
||
|
||
After getting the development sources, and installing the tools above,
|
||
you can run
|
||
./autogen.sh
|
||
and then, for example,
|
||
./configure -C CFLAGS='-g' PERL_EXT_CFLAGS='-g'
|
||
and then
|
||
make
|
||
|
||
The -C tells configure to cache test results, which usually speeds
|
||
things up a bit.
|
||
|
||
After the initial autogen && configure, simply running make should suffice.
|
||
|
||
Gettext or help2man not installed do not cause configure to fail,
|
||
though configure shows if they were found. This is because a release
|
||
does not require those tools. Indeed, both prerequisites and
|
||
result files are shipped in a release, such that the tools are only
|
||
needed if the prerequisite changed. The tools are needed when building
|
||
from developpement sources, however, as result files are not under version
|
||
control. Make will fail with an explicit missing command for help2man,
|
||
and with a command not found error for a Gettext utility command.
|
||
|
||
Running make in one particular subdirectory is possible, for example
|
||
make -C info. However there are interdependencies between the
|
||
subdirectories, notably on gnulib, so if you don't want to run "make",
|
||
you may have to run "make -C gnulib/lib" first.
|
||
|
||
Additionally, make dist may not work until make has been run at least
|
||
once, because of rules to create man pages under the man/ directory.
|
||
|
||
"make dist" will fail if the use of Perl XS extension modules is
|
||
disabled and there is no Makefile in the XSParagraph subdirectory.
|
||
|
||
|
||
Using git
|
||
---------
|
||
|
||
This section is if you have write access to the git repository.
|
||
|
||
Usually commits to the git repository should include a ChangeLog
|
||
entry. Please follow the existing style (the GNU Coding Standards
|
||
has a guide).
|
||
|
||
You can automatically use the contents of the most recent ChangeLog
|
||
entry with a git commit hook .git/hooks/prepare-commit-msg
|
||
|
||
------------------------------------
|
||
#!/bin/sh
|
||
|
||
# $1 - file that contains commit log message
|
||
# $2 - source of commit message
|
||
|
||
outfile="$1"
|
||
|
||
case $2 in
|
||
message|template|merge|squash|commit)
|
||
;;
|
||
*)
|
||
# Use latest ChangeLog entry as commit message
|
||
sed -n -e '1,/^\w*$/d' -e '/^[^ ]/q' -e '{s/^ //;p}' ChangeLog >"$outfile"
|
||
;;
|
||
esac
|
||
------------------------------------
|
||
|
||
When unable to push commits due to other commits being made, please
|
||
use "git pull --rebase" (the default for "git pull" complicates the
|
||
git history). To deal with conflicts in the ChangeLog, you should
|
||
install the git-merge-changelog program.
|
||
|
||
You can get better output from "git diff" for Texinfo files by putting
|
||
the following section in your .gitconfig file:
|
||
|
||
[diff "texinfo"]
|
||
xfuncname = "^(@node .*)$"
|
||
|
||
This shows which node each change occurred in.
|
||
|
||
|
||
Gnulib
|
||
------
|
||
|
||
This distribution uses Gnulib (http://www.gnu.org/software/gnulib)
|
||
to share common files. Gnulib files used in Texinfo are checked in to
|
||
the repository. A Gnulib directory is setup in two locations, in
|
||
the main directory and in tp/Texinfo/XS/.
|
||
|
||
To update the gnulib files, get a checkout of gnulib in a separate
|
||
directory, then run, say
|
||
|
||
../gnulib/gnulib-tool --add-import
|
||
|
||
in your top-level Texinfo directory and
|
||
|
||
../../../../gnulib/gnulib-tool --add-import
|
||
|
||
under tp/Texinfo/XS. (gnulib-tool is in the gnulib source tree.)
|
||
|
||
The currently-used gnulib modules and other gnulib information are
|
||
recorded in gnulib/m4/gnulib-cache.m4.
|
||
|
||
gnulib-tool --add-import may also be used to add another gnulib module:
|
||
../gnulib/gnulib-tool --add-import other_gnulib_module
|
||
|
||
After running gnulib-tool --add-import or otherwise adding modules, it is
|
||
necessary to check what files were added or removed (e.g., run "git
|
||
status -u") and add new files to the repository with "git add".
|
||
Add any new generated files (typically gnulib/lib/foo.h from foo.h.in)
|
||
to the ignore list in .gitignore.
|
||
|
||
|
||
Subdirectories in repository
|
||
----------------------------
|
||
|
||
In addition to the subdirectories listed in README, there is the
|
||
following directory in the source control repository:
|
||
|
||
js/ - Work on enhanced browsing of HTML manuals with JavaScript
|
||
infog/ - HTML-Info reader using WebKitGTK library
|
||
|
||
Finally, the contrib/ directory contains additional files from users
|
||
provided for your reading and/or hacking pleasure. They aren't part of
|
||
Texinfo proper or maintained by the Texinfo developers.
|
||
|
||
|
||
|
||
|
||
About running the Texinfo programs from a development source tree:
|
||
|
||
- Once the distribution is built, you can run the compiled programs
|
||
(info, install-info) out of the build tree without special settings;
|
||
they don't try to read any installed data files.
|
||
|
||
- The texi2dvi script and texinfo.tex can be run as-is, since they
|
||
are standalone and don't require compilation. For the same reasons,
|
||
they are officially updated between full Texinfo releases, at
|
||
http://ftpmirror.gnu.org/texinfo.
|
||
|
||
- Regarding texi2any (aka makeinfo), you can run tp/texi2any.pl
|
||
directly. This is the original source file for the program, so it's
|
||
convenient to be able to make changes and then run it.
|
||
|
||
To run the output "tp/texi2any" instead, you can set the environment
|
||
variable TEXINFO_DEV_SOURCE to 1. Otherwise, it will try to use
|
||
Texinfo's Perl modules in the installed locations. "tp/texi2any" uses
|
||
the Perl interpreter found by configure, so you might want to run that
|
||
instead of texi2any.pl if it's different to the default interpreter in
|
||
your environment.
|
||
|
||
|
||
|
||
References for working on various parts of the system:
|
||
|
||
If you want to delve into making a new backend for the Perl makeinfo,
|
||
the documentation in tp/Texinfo/Convert/Converter.pm is a good starting
|
||
point, as it describes the existing backends and other places to look.
|
||
|
||
If you want to delve into texinfo.tex, a thorough plain TeX reference
|
||
is available under the GFDL:
|
||
TeX by Topic - http://www.eijkhout.net/texbytopic/texbytopic.html
|
||
Another book on plain TeX, also available under the GFDL, is a GNU package:
|
||
TeX for the Impatient - http://www.gnu.org/software/teximpatient/
|
||
Occasionally you may need to know about the details of the PDF format.
|
||
A reference for this is the PDF reference, Sixth Edition, version 1.7,
|
||
downloadable at http://www.adobe.com/devnet/pdf/pdf_reference_archive.html
|
||
|
||
The texindex program is implemented using the TexiWebJR literate
|
||
programming system, combining Texinfo and Awk
|
||
(https://github.com/arnoldrobbins/texiwebjr). Running "make ti.pdf"
|
||
in the texindex/ subdirectory creates the printable form of the
|
||
program. All the usual Texinfo output formats are possible.
|
||
|
||
|
||
|
||
Steps for making a release (pretest or official):
|
||
|
||
- When close to official release:
|
||
|
||
check at latest automake/autoconf/gettext version, and mention in NEWS
|
||
(to upgrade gettext, run
|
||
gettextize -f --po-dir=po --po-dir=po_document
|
||
after installing new version of gettext.
|
||
check that this does not actually downgrade files due to files also
|
||
being updated from gnulib --add-import)
|
||
|
||
# Under the top level, and also under tp/Texinfo/XS, which uses
|
||
# a separate gnulib import.
|
||
gnulib-tool --add-import
|
||
'git status -u' and add untracked files
|
||
|
||
After upgrading automake/autoconf/gettext, run ./autogen.sh
|
||
and/or "autoreconf --verbose --force --install" to update ancilliary
|
||
files in build-aux and elsewhere. Check changes before committing.
|
||
|
||
Use util/srclist-txi for checking files to be copied from gnulib
|
||
|
||
run all tests with valgrind:
|
||
* under info/t, put valgrind in $ginfo, then check t/*.val.log files after
|
||
running test suite
|
||
* edit install-info/tests/defs.in, uncomment valgrind line and run
|
||
config.status to regenerate defs
|
||
|
||
parsetexi memory leak checks with valgrind
|
||
|
||
NYTProf profiling for Perl code
|
||
* e.g. 'perl -d:NYTProf ../tp/texi2any.pl FILE.texi'. See Devel::NYTProf
|
||
man page.
|
||
|
||
|
||
try groff.texinfo from groff source repo.
|
||
Check "make ccheck" and "make vcheck" work in "doc/refcard".
|
||
process doc/texinfo-tex-test.texi with TeX and check that output is good.
|
||
check for C compiler warnings by configuring with
|
||
|
||
./configure CFLAGS='-Wall -Wdeclaration-after-statement' \
|
||
PERL_EXT_CFLAGS='-Wall -Wdeclaration-after-statement'
|
||
|
||
-Wdeclaration-after-statement is useful because a) intermixing
|
||
declarations with statements is an easy thing to do accidentally,
|
||
b) gcc doesn't warn about it by default, and c) other compilers that
|
||
don't support it are still widespread.
|
||
|
||
Not all compiler warnings have to be fixed, though.
|
||
|
||
Have a look at the output of "git status -u" to check for files that
|
||
should be tracked in git or ignored.
|
||
make po-check # update po/POTFILES.in as needed
|
||
|
||
check indices of Texinfo manuals and check for duplicates (with <1> in Info)
|
||
|
||
- Official releases only:
|
||
make V=1 pdf and fix underfull/overfull boxes.
|
||
|
||
- Final (easy) checks:
|
||
|
||
check OpenCSW build reports at
|
||
https://buildfarm.opencsw.org/buildbot/waterfall?category=texinfo
|
||
Check that translations have been updated, e.g.:
|
||
rsync -Lrtzv translationproject.org::tp/latest/texinfo/ po
|
||
rsync -Lrtzv translationproject.org::tp/latest/texinfo_document/ \
|
||
po_document # note the trailing slashes in these commands
|
||
make
|
||
make update-po # both po and po_document needed, build a dist first
|
||
Ensure texinfo.tex, texi2dvi, and htmlxref.cnf are updated on ftp.gnu.org.
|
||
Ensure TXI_XLATE in doc/Makefile.am matches actual file list.
|
||
Check that LINGUAS under po and po_document match actual file list.
|
||
Check that TEXINFO_DTD_VERSION has been updated to the next version in
|
||
configure.ac if the DTD has been modified since the last release.
|
||
See comments in configure.ac, and run (at the top level) make dtd-check.
|
||
Check "dist-xz" is in the option list in configure.ac (often removed
|
||
for speed when testing).
|
||
update version in configure.ac, notice in ChangeLog.
|
||
check up to date copyright years in files relevant to --version calls
|
||
(tp/texi2any.pl, info/info.c, install-info/install-info.c)
|
||
version number in texi2dvi, texi2pdf, txirefcard.tex.
|
||
check that texindex version is updated properly
|
||
(cd texindex ; rm texindex.awk ; make)
|
||
(cd tp && ./maintain/change_perl_modules_version.sh auto)
|
||
-- this updates all the version numbers in the Perl modules
|
||
(cd tp ; maintain/regenerate_file_lists.pl) # list all test results
|
||
|
||
- Official releases only:
|
||
version and date in NEWS.
|
||
version number in txirefcard.tex.
|
||
(cd tp && maintain/regenerate_documentlanguages-loc.pl)
|
||
-- regenerates tp/Texinfo/Documentlanguages.pm (requires Text::CSV)
|
||
|
||
one last "git diff" to check release commit looks good
|
||
make distcheck
|
||
(export MALLOC_CHECK_=2; make distcheck) # repeat until clean
|
||
git commit and push
|
||
|
||
after uploading distribution,
|
||
pretest announcement -> bug-texinfo / beebe / platform-testers to try.
|
||
bcc coordinator@translationproject.org.
|
||
|
||
|
||
|
||
- To do the actual upload:
|
||
pkg=texinfo
|
||
ver=7.0
|
||
|
||
then do one of:
|
||
gnupload --to alpha.gnu.org:$pkg $pkg-$ver.tar.xz #pretest
|
||
gnupload --to ftp.gnu.org:$pkg $pkg-$ver.tar.{gz,xz} *.diff.xz #official
|
||
Use --user option if not using default key
|
||
texinfo.tex and texi2dvi should already be up to date, but check. Use
|
||
gnupload --replace --to ftp.gnu.org:texinfo texi2dvi
|
||
|
||
# Official releases only: tag source tree
|
||
git tag texinfo-6.6
|
||
git push --tags
|
||
|
||
# ... set up dtd directory on web pages:
|
||
cd $HOME/gnu/www/texinfo/dtd # or wherever webpages checkout is
|
||
mkdir $ver && cvs add $ver
|
||
cp $tutil/texinfo.dtd $ver
|
||
cvs add -kb $ver $ver/texinfo.dtd
|
||
cvs commit -m$ver $ver
|
||
|
||
|
||
- When official release is out there ...
|
||
update home page (texinfo.html) and commit as needed.
|
||
including:
|
||
pod2html $txi/Pod-Simple-Texinfo/pod2texi.pl \
|
||
| grep -Fv 'rev="made"' >manual/pod2texi.html
|
||
|
||
check for http links that should be changed to https - then delete
|
||
this item
|
||
|
||
Build web documentation with
|
||
make -C doc wwwdoc-build
|
||
|
||
Copy documentation files to web checkout with, e.g.
|
||
make -C doc \
|
||
wwwdoc-install www_target=../../TEXINFO_WEB_PAGES/texinfo/manual/
|
||
Check for removed files with, e.g. ls -ltu $(www_target)/*/html_node,
|
||
followed by cvs rm -f. Likewise, check for added files with
|
||
cvs -qn update, followed by cvs add. When done, run cvs commit.
|
||
|
||
# Official releases only: Contact root@tug.org to update texinfo at tug.org.
|
||
# If root@tug.org doesn't reply, can try webmaster@tug.org,
|
||
# or (last resort) board@tug.org.
|
||
|
||
|
||
# For official releases:
|
||
send announcement to info-gnu,
|
||
cc bug-texinfo and bcc coordinator@translationproject.org.
|
||
news item at savannah.
|
||
|
||
# ... post-release, or when development resumes:
|
||
configure.ac, util/texi2dvi: add "dev" to versions for clarity,
|
||
until it's time to do pretests again.
|
||
|
||
after next release:
|
||
rename old ChangeLog and start a new one
|
||
check TODO file and do pending tasks
|
||
discuss on mailing list changing the git branch structure to allow quick
|
||
bug fix releases for severe bugs (e.g. glibc 2.34 incompatibility, info crash
|
||
in Brazillian Portuguese locale)
|
||
delete these lines from README-hacking
|
||
|
||
|