diff --git a/.gitignore b/.gitignore index 3b7fce73..8f0fdb3b 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,7 @@ TAGS /doc/inslist.src /doc/version.src /doc/warnings.src +/doc/perlbreq.src /doc/fontpath /doc/Fontmap /include/warnings.h diff --git a/Makefile.in b/Makefile.in index 949df0dd..99768153 100644 --- a/Makefile.in +++ b/Makefile.in @@ -442,7 +442,7 @@ cscope: $(FIND) . -name '*.[hcS]' -print > cscope.files cscope -b -f cscope.out -doc: doc/warnings.src +doc: doc/warnings.src doc/perlbreq.src $(MAKE) -C doc all doc_install install_doc: @@ -478,6 +478,11 @@ perlbreq.si: $(ALLPERLSRC) sed -r -e '/perl\((Win32.*)\)/d' | \ sort | uniq > perlbreq.si +doc/perlbreq.src: perlbreq.si + sed -n -r -e 's/^BuildRequires: perl\((.*)\)$$/\\c \1/p' \ + < perlbreq.si > doc/perlbreq.src + echo '\c Win32 (if building on Windows only)' >> doc/perlbreq.src + nasm.spec: nasm.spec.in nasm.spec.sed version.sed perlbreq.si sed -f version.sed -f nasm.spec.sed \ < nasm.spec.in > nasm.spec diff --git a/doc/Makefile.in b/doc/Makefile.in index f87c7155..c68a4b93 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -20,7 +20,8 @@ INSTALL = @INSTALL@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_DATA = @INSTALL_DATA@ -PERL = perl -I$(top_srcdir)/perllib -I$(srcdir) +PERL = perl +RUNPERL = $(PERL) -I$(top_srcdir)/perllib -I$(srcdir) PDFOPT = @PDFOPT@ @@ -39,7 +40,8 @@ XZFILES = @XZFILES@ # Auxiliary files referenced by the HTML files HTMLAUX = nasmdoc.css local.css nasmlogw.png -SRCS = nasmdoc.src inslist.src changes.src warnings.src version.src +SRCS = nasmdoc.src inslist.src changes.src \ + warnings.src version.src perlbreq.src OUT = html nasmdoc.txt nasmdoc.pdf $(XZFILES) XZOUT = nasmdoc.pdf.xz @@ -59,14 +61,14 @@ all: $(OUT) xzfiles: $(XZOUT) inslist.src: inslist.pl ../x86/insns.dat - $(PERL) $(srcdir)/inslist.pl $(srcdir)/../x86/insns.dat + $(RUNPERL) $^ html: $(HTMLAUX) $(MKDIR_P) html for f in $(HTMLAUX); do $(CP_UF) "$(srcdir)/$$f" html/; done $(MAKE) html/nasmdoc0.html -RDSRC = $(PERL) $(srcdir)/rdsrc.pl -I$(srcdir)/ +RDSRC = $(RUNPERL) $(srcdir)/rdsrc.pl -I$(srcdir)/ html/nasmdoc0.html: $(SRCS) rdsrc.pl $(RM_F) html/*.html @@ -79,12 +81,12 @@ nasmdoc.txt: $(SRCS) rdsrc.pl $(RDSRC) txt nasmdoc.src version.src: $(top_srcdir)/version.pl $(top_srcdir)/version - $(PERL) $(top_srcdir)/version.pl docsrc \ + $(RUNPERL) $(top_srcdir)/version.pl docsrc \ < $(top_srcdir)/version > version.src nasmdoc.ps: nasmdoc.dip genps.pl afmmetrics.ph ttfmetrics.ph \ pswidth.ph nasmlogo.eps psfonts.ph head.ps - $(PERL) $(srcdir)/genps.pl -epsdir "$(srcdir)" \ + $(RUNPERL) $(srcdir)/genps.pl -epsdir "$(srcdir)" \ -headps $(srcdir)/head.ps \ -fontpath fontpath \ -fontmap Fontmap \ @@ -97,11 +99,11 @@ Fontmap: nasmdoc.ps @: Generated by side effect nasmdoc.pdf: nasmdoc.ps pspdf.pl fontpath - $(PERL) $(srcdir)/pspdf.pl \ + $(RUNPERL) $(srcdir)/pspdf.pl \ $(PDFOPT) $< $@ fontpath nasmdoc-raw.pdf: nasmdoc.ps pspdf.pl fontpath - $(PERL) $(srcdir)/pspdf.pl -nocompress \ + $(RUNPERL) $(srcdir)/pspdf.pl -nocompress \ $(PDFOPT) $< $@ fontpath nasmdoc.pdf.xz: nasmdoc-raw.pdf @@ -111,7 +113,7 @@ nasmdoc.pdf.xz: nasmdoc-raw.pdf clean: -$(RM_F) *.rtf *.hpj *.texi *.gid *.ipf *.dip -$(RM_F) *.aux *.cp *.fn *.ky *.pg *.log *.toc *.tp *.vr - -$(RM_F) inslist.src version.src fontpath Fontmap + -$(RM_F) inslist.src version.src perlbreq.src fontpath Fontmap -$(RM_F) nasmdoc*.ps nasmdoc-raw.pdf spotless: clean diff --git a/doc/changes.src b/doc/changes.src index 5ffbb33a..0ae640bc 100644 --- a/doc/changes.src +++ b/doc/changes.src @@ -9,8 +9,7 @@ since 2007. \S{cl-2.17} Version 2.17 -\b ... here goes release notes not intended to be included in the -2.16.xx stable series ... +\b Improve the documentation for building from source (\k{source}). \S{cl-2.16.04} Version 2.16.04 diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src index dbd0cde6..d5ee67a6 100644 --- a/doc/nasmdoc.src +++ b/doc/nasmdoc.src @@ -8946,7 +8946,7 @@ a zero-extended absolute displacement can access from 0 to 4 GB. On Unix, the 64-bit ABI as well as the x32 ABI (32-bit ABI with the CPU in 64-bit mode) is defined by the documents at: -\W{http://www.nasm.us/abi/unix64}\c{http://www.nasm.us/abi/unix64} +\W{https://www.nasm.us/abi/unix64}\c{https://www.nasm.us/abi/unix64} Although written for AT&T-syntax assembly, the concepts apply equally well for NASM-style assembly. What follows is a simplified summary. @@ -8980,7 +8980,7 @@ Integer and SSE register arguments are counted separately, so for the case of The Win64 ABI is described by the document at: -\W{http://www.nasm.us/abi/win64}\c{http://www.nasm.us/abi/win64} +\W{https://www.nasm.us/abi/win64}\c{https://www.nasm.us/abi/win64} What follows is a simplified summary. @@ -9294,32 +9294,109 @@ anyway. \A{source} Building NASM from Source The source code for NASM is available from our website, -\W{http://www.nasm.us/}{http://www.nasm.us/}, see \k{website}. +\w{https://www.nasm.us/}, see \k{website}. \H{tarball} Building from a Source Archive The source archives available on the web site should be capable of building on a number of platforms. This is the recommended method for building NASM to support platforms for which executables are not -available. +available, if you do not require changing the source code. -On a system which has Unix shell (\c{sh}), run: +The preferred build platforms are development environments which +support POSIX (Unix)-style tools (a "POSIX environment"). For Windows, +MSYS2 (\w{https://www.msys2.org/}) is such a development environment. + +In a POSIX environment, run: \c sh configure -\c make everything +\c make A number of options can be passed to \c{configure}; see -\c{sh configure --help}. +\c{sh configure --help}. In particular, the \c{--host} option can be +used to cross-compile NASM to run on another host system. -A set of Makefiles for some other environments are also available; -please see the file \c{Mkfiles/README}. +For non-POSIX environments, a set of Makefiles for some other +environments are also available; please see the file +\c{Mkfiles/README}. -To build the installer for the Windows platform, you will need the -\i\e{Nullsoft Scriptable Installer}, \i{NSIS}, installed. +The \c{.zip} version of the source archive has DOS/Windows line +endings (\c{CR LF}), which many POSIX systems will not recognize. To +extract the \c{.zip} version on such a system, use \c{unzip +-a}. The \c{.tar} versions of the source archive has POSIX line +endings (\c{LF}). + + +\H{buildtools} Optional Build Tools + +The following additional tools are required to build specific +subsystems, to build from the \c{git} repository, or if the sources +are modified. + +Note that some of these tools will have their own dependencies. + +Make sure all tools are available in your \c{PATH} (or equivalent.) + +To build the installer for the Windows platform: + +\b The \i{Nullsoft Scriptable Installer} (\i{NSIS}, +\w{https://nsis-dev.github.io/}). + +To modify the sources, \e{or} to build the documentation: + +\b A Perl interpreter (\w{https://www.perl.org/}). + +\b Modules from CPAN (\w{https://www.cpan.org/}). The following Perl +modules are currently required, some of which will be bundled with the +Perl interpreter or into larger CPAN packages: + +\& perlbreq.src + +To build the documentation: + +\b Either Ghostscript (\w{https://www.ghostscript.com/}) or Adobe +Acrobat Distiller (untested.) + +\b The Adobe \e{Source Sans} (or \e{Source Sans 3}) and \e{Source +Code} fonts, which are freely available under the SIL Open Font +License (\w{https://fonts.adobe.com/}). + +To build the Unix man pages: + +\b AsciiDoc (\w{https://asciidoc.org/}). + +\b xmlto (\w{https://pagure.io/xmlto/}). + +To build from the \c{git} repository on a POSIX platform: + +\b GNU \c{m4}, \c{autoconf} and \c{autoheader} +(\w{https://www.gnu.org/}). + + + +\H{buildopt} Building Optional Components + +Install the required tools for the subsystem in question as described +in \k{buildtools}. + +To build the documentation: + +\c make doc + +Building the documentation may not work in a non-POSIX environment. + +To build the Windows installer: + +\c make nsis + +To build the Unix man pages: + +\c make manpages + +To build everything available on the current platform: + +\c make everything -To build the documentation, you will need a set of additional tools. -The documentation is not likely to be able to build on non-Unix -systems. \H{git} Building from the \i\c{git} Repository @@ -9328,30 +9405,45 @@ the \c{git} distributed source control system. The link is available on the website. This is recommended only to participate in the development of NASM or to assist with testing the development code. -To build NASM from the \c{git} repository you will need a Perl -interpreter and, if building on a Unix system, GNU autoconf installed -on your system. +Install the required tools as described in section \k{buildtools}. -To build on a Unix system, run: +In a POSIX environment: + +Run: \c sh autogen.sh -to create the \c{configure} script and then build as listed above. +to create the \c{configure} script and then build as described in +\k{tarball}. -\H{builddoc} Building the documentation +In a non-POSIX environment, use the tool-specific Makefiles +as described in \k{tarball}. + + +\H{modifysrc} Modifying the Sources + +To build modified sources, you will need the tools described in +\k{buildtools}. + +Some build system changes might not be possible without a POSIX +environment. + +If you have modified the sources to change the embedded declarations +of warning classes, you may have to manually re-build the warning +catalog: + +\c make warnings + +This is not done automatically, as the tools do not have the ability +to automatically detect when it is necessary to do so. -To build the documentation, you will need a Perl interpreter, a -Postscript to PDF converter such as Ghostscript, and suitable fonts -installed on your system. The recommended (and default) fonts are -Adobe's Source Sans and Source Code fonts, which are freely available -under the SIL Open Font License. \A{contact} Contact Information \H{website} Website NASM has a \i{website} at -\W{http://www.nasm.us/}\c{http://www.nasm.us/}. +\w{https://www.nasm.us/}. \i{New releases}, \i{release candidates}, and \I{snapshots, daily development}\i{daily development snapshots} of NASM are available from @@ -9374,7 +9466,7 @@ links and archives of past posts are available on the website. \H{bugs} \i{Reporting Bugs}\I{bugs} To report bugs in NASM, please use the \i{bug tracker} at -\W{http://www.nasm.us/}\c{http://www.nasm.us/} (click on "Bug +\w{https://www.nasm.us/} (click on "Bug Tracker"), or if that fails then through one of the contacts in \k{website}.