CMake infrastructure does not handle documentation

[dl8dtl]

The new CMake infrastructure does not handle documentation:

• there is no way to build the docs below doc/
• the man page avrdude.1 is not installed during make install

[mariusgreuel]

there is no way to build the docs below doc/

I remember I saved this part for later as we were not clear on how to handle the docs. As we do have Github pages for the manual, we only need the man page from the CMake build, correct?

the man page avrdude.1 is not installed during make install

will do

[dl8dtl]

there is no way to build the docs below doc/

I remember I saved this part for later as we were not clear on how to handle the docs. As we do have Github pages for the manual, we only need the man page from the CMake build, correct?

No, the Github pages are just copied over from the texinfo build right now, but the commands how to create the docs out of the texinfo source are only in the classic automake files so far.

Until we found someone volunteering to setup a better way, we'd thus somehow need to preserve the texinfo toolchain in the CMake infrastructure.

Also, it would be great to include all that inside the source tarball, as it used to be the case with automake. That way, people (e.g. like Linux or FreeBSD distributors) could decide to (optionally) compile and install the appropriate documentation locally, rather than only referring to the online docs. For automake, this was achieved by ./configure --enable-doc.

the man page avrdude.1 is not installed during make install

will do

tnx!

[sbngross]

So the first part seems to work at least on linux. See #1064

For the second part I am digging into doc/Makefile.am right now. Could you give me a hint where version.texi is supposed to come from? I find no reference in Makefile.am as with the other generated files. Is this supposed to be the git tag?

Maybe it would be easiest if you could provide a working command - I have no idea of how that .am stuff works - so I can verify that the cmake part behaves exactly the same.

Will pdflatex suffice or do i need some extra magic like sphinx?

[stefanrueger]

The project moved from make to cmake relatively recently (considering AVRDUDE will be 20 years old in February). I would expect that both version.texi and avrdude.pdf can be generated sth like the following

cd src
./bootstrap
./configure
cd doc
make version.texi avrdude.pdf

[mcuee]

I have never tried to build the documentation before and the above works fine under Linux. I need to install texlive to build the documentation.

mcuee@UbuntuSwift3:~/build/avr/avrdude/src/build/doc$ make version.texi avrdude.pdf avrdude.dvi 
avrdude.ps avrdude.html
../avrdude -C ../avrdude.conf -c \? 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,gensub("[^=]+=[ \t]*","",1))}' \
| sed "s# *,\? *<\?\(http://[^ \t>]*\)>\?#,@*\n@url{\1}#g" \
>programmers.texi
../avrdude -C ../avrdude.conf -p \? 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,$3)}' \
| sed -e "`sed 's:\([^ \t]*\)[ \t]*\(.*\):s/\1$/\1 \2/g:g' <parts_comments.txt`" \
>parts.texi
/bin/bash: line 2: parts_comments.txt: No such file or directory
../avrdude -C ../avrdude.conf -c \?type 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,gensub("[^=]+=[ \t]*","",1))}' \
| sed "s#<\?\(http://[^ \t,>]*\)>\?#@url{\1}#g" \
>programmer_types.texi
  TEXI2PDF avrdude.pdf
  TEXI2DVI avrdude.dvi
  DVIPS    avrdude.ps
  MAKEINFO avrdude.html
mcuee@UbuntuSwift3:~/build/avr/avrdude/src/build/doc$ ls
avrdude.dvi   avrdude.pdf  avrdude.t2d  Makefile    programmers.texi
avrdude.html  avrdude.ps   avrdude.t2p  parts.texi  programmer_types.texi

I am not so sure about the /bin/bash: line 2: parts_comments.txt: No such file or directory error though.

[sbngross]

Thanks. Works like a charm. I'm now looking into it but I'm not too fluid in autohell so it may take a while. For starters I am going to take version.texi and texinfo.tex for granted and try to go from there.

One question ahead version.texi seems to be fed with mtime which is fine for the tarball but not for git I think. One might want to adapt that while we're at it as well.

[mcuee]

I am not so sure about the /bin/bash: line 2: parts_comments.txt: No such file or directory error though.

This seems to only happen if I creatthened the build director under src and then use ../configure in the build directory -- out of tree build. If not using out-of-tree build then it is okay.

build log

mcuee@UbuntuSwift3:~/build/avr/avrdude/src$ ./configure 
...
Configuration summary:
----------------------
DO HAVE    libelf
DO HAVE    libusb
DO HAVE    libusb_1_0
DO HAVE    libftdi1
DO HAVE    libftdi (but prefer to use libftdi1)
DON'T HAVE libhid
DO HAVE    libhidapi
DO HAVE    pthread
DISABLED   doc
DISABLED   parport
DISABLED   linuxgpio
DISABLED   linuxspi
mcuee@UbuntuSwift3:~/build/avr/avrdude/src$ cd doc/
mcuee@UbuntuSwift3:~/build/avr/avrdude/src/doc$ make version.texi avrdude.pdf avrdude.dvi avrdude.ps avrdude.html
make: Nothing to be done for 'version.texi'.
make -C .. avrdude
make[1]: Entering directory '/home/mcuee/build/avr/avrdude/src'
  CC       avrdude-main.o
  CC       avrdude-whereami.o
  CC       avrdude-developer_opts.o
  CC       avrdude-term.o
  YACC     config_gram.c
updating config_gram.h
  CC       libavrdude_a-config_gram.o
  LEX      lexer.c
  CC       libavrdude_a-lexer.o
  CC       libavrdude_a-arduino.o
  CC       libavrdude_a-avr.o
  CC       libavrdude_a-avr910.o
  CC       libavrdude_a-avrftdi.o
  CC       libavrdude_a-avrftdi_tpi.o
  CC       libavrdude_a-avrpart.o
  CC       libavrdude_a-bitbang.o
  CC       libavrdude_a-buspirate.o
  CC       libavrdude_a-butterfly.o
  CC       libavrdude_a-config.o
  CC       libavrdude_a-confwin.o
  CC       libavrdude_a-crc16.o
  CC       libavrdude_a-dfu.o
  CC       libavrdude_a-fileio.o
  CC       libavrdude_a-flip1.o
  CC       libavrdude_a-flip2.o
  CC       libavrdude_a-ft245r.o
  CC       libavrdude_a-jtagmkI.o
  CC       libavrdude_a-jtagmkII.o
  CC       libavrdude_a-jtag3.o
  CC       libavrdude_a-linuxgpio.o
  CC       libavrdude_a-linuxspi.o
  CC       libavrdude_a-lists.o
  CC       libavrdude_a-micronucleus.o
  CC       libavrdude_a-par.o
  CC       libavrdude_a-pgm.o
  CC       libavrdude_a-pgm_type.o
  CC       libavrdude_a-pickit2.o
  CC       libavrdude_a-pindefs.o
  CC       libavrdude_a-ppi.o
  CC       libavrdude_a-ppiwin.o
  CC       libavrdude_a-serbb_posix.o
  CC       libavrdude_a-serbb_win32.o
  CC       libavrdude_a-ser_avrdoper.o
  CC       libavrdude_a-ser_posix.o
  CC       libavrdude_a-ser_win32.o
  CC       libavrdude_a-stk500.o
  CC       libavrdude_a-stk500v2.o
  CC       libavrdude_a-stk500generic.o
  CC       libavrdude_a-teensy.o
  CC       libavrdude_a-usbasp.o
  CC       libavrdude_a-serialupdi.o
  CC       libavrdude_a-updi_link.o
  CC       libavrdude_a-updi_state.o
  CC       libavrdude_a-updi_readwrite.o
  CC       libavrdude_a-updi_nvm.o
  CC       libavrdude_a-usb_hidapi.o
  CC       libavrdude_a-usb_libusb.o
  CC       libavrdude_a-usbtiny.o
  CC       libavrdude_a-update.o
  CC       libavrdude_a-wiring.o
  CC       libavrdude_a-xbee.o
  AR       libavrdude.a
ar: `u' modifier ignored since `D' is the default (see `U')
  CCLD     avrdude
make[1]: Leaving directory '/home/mcuee/build/avr/avrdude/src'
../avrdude -C ../avrdude.conf -c \? 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,gensub("[^=]+=[ \t]*","",1))}' \
| sed "s# *,\? *<\?\(http://[^ \t>]*\)>\?#,@*\n@url{\1}#g" \
>programmers.texi
../avrdude -C ../avrdude.conf -p \? 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,$3)}' \
| sed -e "`sed 's:\([^ \t]*\)[ \t]*\(.*\):s/\1$/\1 \2/g:g' <parts_comments.txt`" \
>parts.texi
../avrdude -C ../avrdude.conf -c \?type 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,gensub("[^=]+=[ \t]*","",1))}' \
| sed "s#<\?\(http://[^ \t,>]*\)>\?#@url{\1}#g" \
>programmer_types.texi
  TEXI2PDF avrdude.pdf
  TEXI2DVI avrdude.dvi
  DVIPS    avrdude.ps
  MAKEINFO avrdude.html

[mcuee]

Using ./configure --enable-doc also works fine.

build log

mcuee@UbuntuSwift3:~/build/avr/avrdude/src$ ./configure --enable-doc
...
Configuration summary:
----------------------
DO HAVE    libelf
DO HAVE    libusb
DO HAVE    libusb_1_0
DO HAVE    libftdi1
DO HAVE    libftdi (but prefer to use libftdi1)
DON'T HAVE libhid
DO HAVE    libhidapi
DO HAVE    pthread
ENABLED    doc
DISABLED   parport
DISABLED   linuxgpio
DISABLED   linuxspi
mcuee@UbuntuSwift3:~/build/avr/avrdude/src$ make
  YACC     config_gram.c
updating config_gram.h
  LEX      lexer.c
make  all-recursive
make[1]: Entering directory '/home/mcuee/build/avr/avrdude/src'
Making all in .
make[2]: Entering directory '/home/mcuee/build/avr/avrdude/src'
  CC       avrdude-main.o
  CC       avrdude-whereami.o
  CC       avrdude-developer_opts.o
  CC       avrdude-term.o
  CC       libavrdude_a-config_gram.o
  CC       libavrdude_a-lexer.o
  CC       libavrdude_a-arduino.o
  CC       libavrdude_a-avr.o
  CC       libavrdude_a-avr910.o
  CC       libavrdude_a-avrftdi.o
  CC       libavrdude_a-avrftdi_tpi.o
  CC       libavrdude_a-avrpart.o
  CC       libavrdude_a-bitbang.o
  CC       libavrdude_a-buspirate.o
  CC       libavrdude_a-butterfly.o
  CC       libavrdude_a-config.o
  CC       libavrdude_a-confwin.o
  CC       libavrdude_a-crc16.o
  CC       libavrdude_a-dfu.o
  CC       libavrdude_a-fileio.o
  CC       libavrdude_a-flip1.o
  CC       libavrdude_a-flip2.o
  CC       libavrdude_a-ft245r.o
  CC       libavrdude_a-jtagmkI.o
  CC       libavrdude_a-jtagmkII.o
  CC       libavrdude_a-jtag3.o
  CC       libavrdude_a-linuxgpio.o
  CC       libavrdude_a-linuxspi.o
  CC       libavrdude_a-lists.o
  CC       libavrdude_a-micronucleus.o
  CC       libavrdude_a-par.o
  CC       libavrdude_a-pgm.o
  CC       libavrdude_a-pgm_type.o
  CC       libavrdude_a-pickit2.o
  CC       libavrdude_a-pindefs.o
  CC       libavrdude_a-ppi.o
  CC       libavrdude_a-ppiwin.o
  CC       libavrdude_a-serbb_posix.o
  CC       libavrdude_a-serbb_win32.o
  CC       libavrdude_a-ser_avrdoper.o
  CC       libavrdude_a-ser_posix.o
  CC       libavrdude_a-ser_win32.o
  CC       libavrdude_a-stk500.o
  CC       libavrdude_a-stk500v2.o
  CC       libavrdude_a-stk500generic.o
  CC       libavrdude_a-teensy.o
  CC       libavrdude_a-usbasp.o
  CC       libavrdude_a-serialupdi.o
  CC       libavrdude_a-updi_link.o
  CC       libavrdude_a-updi_state.o
  CC       libavrdude_a-updi_readwrite.o
  CC       libavrdude_a-updi_nvm.o
  CC       libavrdude_a-usb_hidapi.o
  CC       libavrdude_a-usb_libusb.o
  CC       libavrdude_a-usbtiny.o
  CC       libavrdude_a-update.o
  CC       libavrdude_a-wiring.o
  CC       libavrdude_a-xbee.o
  AR       libavrdude.a
ar: `u' modifier ignored since `D' is the default (see `U')
  CCLD     avrdude
  CC       libavrdude_la-config_gram.lo
  CC       libavrdude_la-lexer.lo
  CC       libavrdude_la-arduino.lo
  CC       libavrdude_la-avr.lo
  CC       libavrdude_la-avr910.lo
  CC       libavrdude_la-avrftdi.lo
  CC       libavrdude_la-avrftdi_tpi.lo
  CC       libavrdude_la-avrpart.lo
  CC       libavrdude_la-bitbang.lo
  CC       libavrdude_la-buspirate.lo
  CC       libavrdude_la-butterfly.lo
  CC       libavrdude_la-config.lo
  CC       libavrdude_la-confwin.lo
  CC       libavrdude_la-crc16.lo
  CC       libavrdude_la-dfu.lo
  CC       libavrdude_la-fileio.lo
  CC       libavrdude_la-flip1.lo
  CC       libavrdude_la-flip2.lo
  CC       libavrdude_la-ft245r.lo
  CC       libavrdude_la-jtagmkI.lo
  CC       libavrdude_la-jtagmkII.lo
  CC       libavrdude_la-jtag3.lo
  CC       libavrdude_la-linuxgpio.lo
  CC       libavrdude_la-linuxspi.lo
  CC       libavrdude_la-lists.lo
  CC       libavrdude_la-micronucleus.lo
  CC       libavrdude_la-par.lo
  CC       libavrdude_la-pgm.lo
  CC       libavrdude_la-pgm_type.lo
  CC       libavrdude_la-pickit2.lo
  CC       libavrdude_la-pindefs.lo
  CC       libavrdude_la-ppi.lo
  CC       libavrdude_la-ppiwin.lo
  CC       libavrdude_la-serbb_posix.lo
  CC       libavrdude_la-serbb_win32.lo
  CC       libavrdude_la-ser_avrdoper.lo
  CC       libavrdude_la-ser_posix.lo
  CC       libavrdude_la-ser_win32.lo
  CC       libavrdude_la-stk500.lo
  CC       libavrdude_la-stk500v2.lo
  CC       libavrdude_la-stk500generic.lo
  CC       libavrdude_la-teensy.lo
  CC       libavrdude_la-usbasp.lo
  CC       libavrdude_la-serialupdi.lo
  CC       libavrdude_la-updi_link.lo
  CC       libavrdude_la-updi_state.lo
  CC       libavrdude_la-updi_readwrite.lo
  CC       libavrdude_la-updi_nvm.lo
  CC       libavrdude_la-usb_hidapi.lo
  CC       libavrdude_la-usb_libusb.lo
  CC       libavrdude_la-usbtiny.lo
  CC       libavrdude_la-update.lo
  CC       libavrdude_la-wiring.lo
  CC       libavrdude_la-xbee.lo
  CCLD     libavrdude.la
make[2]: Leaving directory '/home/mcuee/build/avr/avrdude/src'
Making all in doc
make[2]: Entering directory '/home/mcuee/build/avr/avrdude/src/doc'
../avrdude -C ../avrdude.conf -c \? 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,gensub("[^=]+=[ \t]*","",1))}' \
| sed "s# *,\? *<\?\(http://[^ \t>]*\)>\?#,@*\n@url{\1}#g" \
>programmers.texi
../avrdude -C ../avrdude.conf -p \? 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,$3)}' \
| sed -e "`sed 's:\([^ \t]*\)[ \t]*\(.*\):s/\1$/\1 \2/g:g' <parts_comments.txt`" \
>parts.texi
../avrdude -C ../avrdude.conf -c \?type 2>&1 \
| gawk '$2 ~ /^=$/ {printf("@item @code{%s} @tab %s\n",$1,gensub("[^=]+=[ \t]*","",1))}' \
| sed "s#<\?\(http://[^ \t,>]*\)>\?#@url{\1}#g" \
>programmer_types.texi
  MAKEINFO avrdude.info
texi2html --split=node --css-include=./avrdude.css ./avrdude.texi
if [ -e ./avrdude.html -o -e ./avrdude_1.html ]; then \
 mkdir -p avrdude-html ; \
 mv -f *.html avrdude-html ; \
else \
 mv -f avrdude avrdude-html; \
fi;
  TEXI2DVI avrdude.dvi
  DVIPS    avrdude.ps
  TEXI2PDF avrdude.pdf
make[2]: Leaving directory '/home/mcuee/build/avr/avrdude/src/doc'
make[1]: Leaving directory '/home/mcuee/build/avr/avrdude/src'

[sbngross]

https://github.com/avrdudes/avrdude/compare/main...sbngross:WIP-cmake-docs

This is what I came up with so far. The basic idea is to do the actual work in scripts and let cmake just handle the dependencies. So the boilerplate stands IMO and only some scripts have to be filled with live. Also the necessary magic for detecting required executables in a OS agnostic fashion has to be added.

How do you build on Windows? WSL or cygwin? I might be able to test both but cygwin with less hazzle.

[mcuee]

How do you build on Windows? WSL or cygwin? I might be able to test both but cygwin with less hazzle.

The wiki has instructions for MSVC, MSY2 mingw32/64 and Cygwin. I usually use MSYS2 and occassionally use MSVC.

Cygwin should work. https://github.com/avrdudes/avrdude/wiki/Building-AVRDUDE-for-Windows-using-Cygwin

[sbngross]

Almost there.

makeinfo is called with correct parameters from the gen_doc.sh script.

cmake -S avrdude -B build_linux -DCMAKE_INSTALL_PREFIX=/home/brutzzl3r/sandbox/opt -DBUILD_DOC=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build_linux --target doc_target

Seems to work on my machine

brutzzl3r@diamond-tiara ~ % uname -a
Linux diamond-tiara 5.18.16-arch1-1 #1 SMP PREEMPT_DYNAMIC Wed, 03 Aug 2022 11:25:04 +0000 x86_64 GNU/Linux
brutzzl3r@diamond-tiara ~ % makeinfo --version
texi2any (GNU texinfo) 6.8
brutzzl3r@diamond-tiara ~ % pdflatex --version
pdfTeX 3.141592653-2.6-1.40.24 (TeX Live 2022/Arch Linux)
kpathsea version 6.3.4
Compiled with libpng 1.6.37; using libpng 1.6.37
Compiled with zlib 1.2.12; using zlib 1.2.12
Compiled with xpdf version 4.03
brutzzl3r@diamond-tiara ~ % cmake --version
cmake version 3.23.3

[sbngross]

Remaining Tasks (feel free to contribute)

• [x] determine if dependency on main executable is really needed and act accordingly
• [x] add checks for required libs and tools, ie makeinfo
• [x] implement version generation
• [x] implement other texi's
• [x] cleanup code, drop some comments here and there
• [ ] maybe clean up commits too in order to make changes more comprehensible for outsiders
• [x] include git version in version string for "flavors" (tag, custom, dirty) if wanted
• [x] handle pdflatex output spam
• [ ] install docs tarball for distro maintainers as suggested by @dl8dtl
• [ ] checks for other OS's
  • [ ] debian based
  • [ ] rhel/fedora maybe?
  • [ ] windows stuff
  • [ ] macos
  • [ ] BSD ?

[mcuee]

Somehow it does not work on my Ubuntu 20.04 system.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake -B build_linux -DCMAKE_INSTALL_PREFIX=/home/mcuee/bin -DBUILD_DOC=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo 
-- The C compiler identification is GNU 9.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Found Git: /usr/bin/git (found version "2.25.1") 
-- Found FLEX: /usr/bin/flex (found version "2.6.4") 
-- Found BISON: /usr/bin/bison (found version "3.5.1")
-- Looking for libelf.h
-- Looking for libelf.h - found
-- Looking for libelf/libelf.h
-- Looking for libelf/libelf.h - not found
-- Looking for usb.h
-- Looking for usb.h - found
-- Looking for lusb0_usb.h
-- Looking for lusb0_usb.h - not found
-- Looking for libusb.h
-- Looking for libusb.h - not found
-- Looking for libusb-1.0/libusb.h
-- Looking for libusb-1.0/libusb.h - found
-- Looking for hidapi/hidapi.h
-- Looking for hidapi/hidapi.h - found
-- Looking for ftdi_tcioflush
-- Looking for ftdi_tcioflush - found
CMake Warning (dev) at src/doc/CMakeLists.txt:27 (configure_file):
  configure_file called with unknown argument(s):

   FILE_PERMISSIONS
   OWNER_EXECUTE
   OWNER_READ

This warning is for project developers.  Use -Wno-dev to suppress it.

CMake Warning (dev) at src/doc/CMakeLists.txt:33 (configure_file):
  configure_file called with unknown argument(s):

   FILE_PERMISSIONS
   OWNER_EXECUTE
   OWNER_READ

This warning is for project developers.  Use -Wno-dev to suppress it.

CMake Error at src/doc/CMakeLists.txt:43 (file):
  file COPY cannot find
  "/home/mcuee/build/avr/avrdude_sbn/src/doc/generator": No such file or
  directory.


-- Configuration summary:
-- ----------------------
-- DO HAVE    libelf
-- DO HAVE    libusb
-- DO HAVE    libusb_1_0
-- DO HAVE    libhidapi
-- DO HAVE    libftdi (but prefer to use libftdi1)
-- DO HAVE    libftdi1
-- ENABLED    doc
-- DISABLED   parport
-- DISABLED   linuxgpio
-- DISABLED   linuxspi
-- ----------------------
-- Configuring incomplete, errors occurred!
See also "/home/mcuee/build/avr/avrdude_sbn/build_linux/CMakeFiles/CMakeOutput.log".
See also "/home/mcuee/build/avr/avrdude_sbn/build_linux/CMakeFiles/CMakeError.log".

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ uname -a
Linux UbuntuSwift3 5.15.10-051510-generic #202112171031 SMP Fri Dec 17 10:53:39 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ makeinfo --version
texi2any (GNU texinfo) 6.7

Copyright (C) 2017 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ pdflatex --version
pdfTeX 3.14159265-2.6-1.40.20 (TeX Live 2019/Debian)
kpathsea version 6.3.1
Copyright 2019 Han The Thanh (pdfTeX) et al.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the pdfTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the pdfTeX source.
Primary author of pdfTeX: Han The Thanh (pdfTeX) et al.
Compiled with libpng 1.6.37; using libpng 1.6.37
Compiled with zlib 1.2.11; using zlib 1.2.11
Compiled with xpdf version 4.01

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake --version
cmake version 3.16.3

CMake suite maintained and supported by Kitware (kitware.com/cmake).

[sbngross]

CMake Warning (dev) at src/doc/CMakeLists.txt:27 (configure_file): configure_file called with unknown argument(s): FILE_PERMISSIONS OWNER_EXECUTE OWNER_READ

Well I guessed that could happen but I thought I looked it up in the docs if this works for 3.16.

configure_file does not like permissions. We can circumvent that with calling copy afterwards.

However this is not the reason it failed though it would have for certain later XD

generator should be in the repo... but I must have forgotten to add it.

Hold on a sec =)

[sbngross]

@sbngross pings @mcuee. You may try again =)

git did not warn me about ignored files i wanted to add therefore generator was missing

[mcuee]

Now the first step is okay but there is a problem with gen_texi.sh under Ubuntu 20.04.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake -B build_linux -DCMAKE_INSTALL_PREFIX=/home/mcuee/bin -DBUILD_DOC=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo 
-- The C compiler identification is GNU 9.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Found Git: /usr/bin/git (found version "2.25.1") 
-- Found FLEX: /usr/bin/flex (found version "2.6.4") 
-- Found BISON: /usr/bin/bison (found version "3.5.1")
-- Looking for libelf.h
-- Looking for libelf.h - found
-- Looking for libelf/libelf.h
-- Looking for libelf/libelf.h - not found
-- Looking for usb.h
-- Looking for usb.h - found
-- Looking for lusb0_usb.h
-- Looking for lusb0_usb.h - not found
-- Looking for libusb.h
-- Looking for libusb.h - not found
-- Looking for libusb-1.0/libusb.h
-- Looking for libusb-1.0/libusb.h - found
-- Looking for hidapi/hidapi.h
-- Looking for hidapi/hidapi.h - found
-- Looking for ftdi_tcioflush
-- Looking for ftdi_tcioflush - found
-- Configuration summary:
-- ----------------------
-- DO HAVE    libelf
-- DO HAVE    libusb
-- DO HAVE    libusb_1_0
-- DO HAVE    libhidapi
-- DO HAVE    libftdi (but prefer to use libftdi1)
-- DO HAVE    libftdi1
-- ENABLED    doc
-- DISABLED   parport
-- DISABLED   linuxgpio
-- DISABLED   linuxspi
-- ----------------------
-- Configuring done
-- Generating done
-- Build files have been written to: /home/mcuee/build/avr/avrdude_sbn/build_linux
mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake --build build_linux --target doc_target
Scanning dependencies of target programmers.texi_target
[ 12%] Generating programmers.texi
./gen_texi.sh: 14: Syntax error: "(" unexpected
make[3]: *** [src/doc/CMakeFiles/programmers.texi_target.dir/build.make:61: src/doc/programmers.texi] Error 2
make[2]: *** [CMakeFiles/Makefile2:205: src/doc/CMakeFiles/programmers.texi_target.dir/all] Error 2
make[1]: *** [CMakeFiles/Makefile2:416: src/doc/CMakeFiles/doc_target.dir/rule] Error 2

[mcuee]

The above seems to be a Ubuntu shell problem (using dash and not bash), a dirty fix (not the right fix) can sort out the above issue but then there is another issue later.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ ls -la /bin/sh
lrwxrwxrwx 1 root root 4 Nov 13  2021 /bin/sh -> dash

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ git diff
diff --git a/src/doc/gen_doc.sh.in b/src/doc/gen_doc.sh.in
index dca9d47..6d626b3 100644
--- a/src/doc/gen_doc.sh.in
+++ b/src/doc/gen_doc.sh.in
@@ -1,4 +1,4 @@
-#!/bin/sh -e
+#!/bin/bash -e
 
 if [ -n "@SCRIPT_DEBUG@" ]
 then
diff --git a/src/doc/gen_texi.sh.in b/src/doc/gen_texi.sh.in
index 04c2cd5..da48c2d 100644
--- a/src/doc/gen_texi.sh.in
+++ b/src/doc/gen_texi.sh.in
@@ -1,4 +1,4 @@
-#!/bin/sh -e
+#!/bin/bash -e
 
 if [ -n "@SCRIPT_DEBUG@" ]
 then

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake --build build_linux --target doc_target
Scanning dependencies of target programmer_types.texi_target
[ 12%] Generating programmer_types.texi
[ 12%] Built target programmer_types.texi_target
Scanning dependencies of target parts.texi_target
[ 25%] Generating parts.texi
[ 25%] Built target parts.texi_target
Scanning dependencies of target programmers.texi_target
[ 37%] Generating programmers.texi
[ 37%] Built target programmers.texi_target
Scanning dependencies of target version.texi_target
[ 50%] Generating version.texi
fatal: No names found, cannot describe anything.
make[3]: *** [src/doc/CMakeFiles/version.texi_target.dir/build.make:61: src/doc/version.texi] Error 128
make[2]: *** [CMakeFiles/Makefile2:262: src/doc/CMakeFiles/version.texi_target.dir/all] Error 2
make[1]: *** [CMakeFiles/Makefile2:416: src/doc/CMakeFiles/doc_target.dir/rule] Error 2
make: *** [Makefile:294: doc_target] Error 2

More info with verbose Makefile option (-DCMAKE_VERBOSE_MAKEFILE=ON)

Scanning dependencies of target version.texi_target
make[3]: Leaving directory '/home/mcuee/build/avr/avrdude_sbn/build_linux'
/usr/bin/make -f src/doc/CMakeFiles/version.texi_target.dir/build.make src/doc/CMakeFiles/version.texi_target.dir/build
make[3]: Entering directory '/home/mcuee/build/avr/avrdude_sbn/build_linux'
[ 50%] Generating version.texi
cd /home/mcuee/build/avr/avrdude_sbn/build_linux/src/doc && ./gen_texi.sh version.texi
fatal: No names found, cannot describe anything.
make[3]: *** [src/doc/CMakeFiles/version.texi_target.dir/build.make:64: src/doc/version.texi] Error 128
make[3]: Leaving directory '/home/mcuee/build/avr/avrdude_sbn/build_linux'
make[2]: *** [CMakeFiles/Makefile2:265: src/doc/CMakeFiles/version.texi_target.dir/all] Error 2

The above error comes from git.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ git -C /home/mcuee/build/avr/avrdude_sbn describe --tags
fatal: No names found, cannot describe anything.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ git --version
git version 2.25.1

Adding --always fixed the issue.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ git describe --tags --always
84b0b96

[mcuee]

In summary, under Ubuntu Linux 20.04, I need to use the following dirty fix.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ git diff
diff --git a/src/doc/gen_doc.sh.in b/src/doc/gen_doc.sh.in
index dca9d47..6d626b3 100644
--- a/src/doc/gen_doc.sh.in
+++ b/src/doc/gen_doc.sh.in
@@ -1,4 +1,4 @@
-#!/bin/sh -e
+#!/bin/bash -e
 
 if [ -n "@SCRIPT_DEBUG@" ]
 then
diff --git a/src/doc/gen_texi.sh.in b/src/doc/gen_texi.sh.in
index 04c2cd5..7483461 100644
--- a/src/doc/gen_texi.sh.in
+++ b/src/doc/gen_texi.sh.in
@@ -1,4 +1,4 @@
-#!/bin/sh -e
+#!/bin/bash -e
 
 if [ -n "@SCRIPT_DEBUG@" ]
 then
@@ -25,7 +25,7 @@ function call_avrdude()
 # This one is a special case so handle it before the others
 if [ "${OUT_FILE}" = "version.texi" ]
 then
-       git -C @CMAKE_SOURCE_DIR@ describe --tags
+       git -C @CMAKE_SOURCE_DIR@ describe --tags --always
        cp generator/${OUT_FILE} .
        exit 0
 fi

After that it will be okay. The HTML files are inside the avrdude directory.

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake -B build_linux -DCMAKE_INSTALL_PREFIX=/home/mcuee/bin -DBUILD_DOC=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
-- The C compiler identification is GNU 9.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Found Git: /usr/bin/git (found version "2.25.1") 
-- Found FLEX: /usr/bin/flex (found version "2.6.4") 
-- Found BISON: /usr/bin/bison (found version "3.5.1")
-- Looking for libelf.h
-- Looking for libelf.h - found
-- Looking for libelf/libelf.h
-- Looking for libelf/libelf.h - not found
-- Looking for usb.h
-- Looking for usb.h - found
-- Looking for lusb0_usb.h
-- Looking for lusb0_usb.h - not found
-- Looking for libusb.h
-- Looking for libusb.h - not found
-- Looking for libusb-1.0/libusb.h
-- Looking for libusb-1.0/libusb.h - found
-- Looking for hidapi/hidapi.h
-- Looking for hidapi/hidapi.h - found
-- Looking for ftdi_tcioflush
-- Looking for ftdi_tcioflush - found
-- Configuration summary:
-- ----------------------
-- DO HAVE    libelf
-- DO HAVE    libusb
-- DO HAVE    libusb_1_0
-- DO HAVE    libhidapi
-- DO HAVE    libftdi (but prefer to use libftdi1)
-- DO HAVE    libftdi1
-- ENABLED    doc
-- DISABLED   parport
-- DISABLED   linuxgpio
-- DISABLED   linuxspi
-- ----------------------
-- Configuring done
-- Generating done
-- Build files have been written to: /home/mcuee/build/avr/avrdude_sbn/build_linux
mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ cmake --build build_linux
[  1%] [BISON][Parser] Building parser with bison 3.5.1
[  2%] [FLEX][Parser] Building scanner with flex 2.6.4
Scanning dependencies of target libavrdude
[  4%] Building C object src/CMakeFiles/libavrdude.dir/arduino.c.o
[  5%] Building C object src/CMakeFiles/libavrdude.dir/avr.c.o
[  7%] Building C object src/CMakeFiles/libavrdude.dir/avr910.c.o
[  8%] Building C object src/CMakeFiles/libavrdude.dir/avrftdi.c.o
[ 10%] Building C object src/CMakeFiles/libavrdude.dir/avrftdi_tpi.c.o
[ 11%] Building C object src/CMakeFiles/libavrdude.dir/avrpart.c.o
[ 12%] Building C object src/CMakeFiles/libavrdude.dir/bitbang.c.o
[ 14%] Building C object src/CMakeFiles/libavrdude.dir/buspirate.c.o
[ 15%] Building C object src/CMakeFiles/libavrdude.dir/butterfly.c.o
[ 17%] Building C object src/CMakeFiles/libavrdude.dir/config.c.o
[ 18%] Building C object src/CMakeFiles/libavrdude.dir/confwin.c.o
[ 20%] Building C object src/CMakeFiles/libavrdude.dir/crc16.c.o
[ 21%] Building C object src/CMakeFiles/libavrdude.dir/dfu.c.o
[ 22%] Building C object src/CMakeFiles/libavrdude.dir/fileio.c.o
[ 24%] Building C object src/CMakeFiles/libavrdude.dir/flip1.c.o
[ 25%] Building C object src/CMakeFiles/libavrdude.dir/flip2.c.o
[ 27%] Building C object src/CMakeFiles/libavrdude.dir/ft245r.c.o
[ 28%] Building C object src/CMakeFiles/libavrdude.dir/jtagmkI.c.o
[ 30%] Building C object src/CMakeFiles/libavrdude.dir/jtagmkII.c.o
[ 31%] Building C object src/CMakeFiles/libavrdude.dir/jtag3.c.o
[ 32%] Building C object src/CMakeFiles/libavrdude.dir/linuxgpio.c.o
[ 34%] Building C object src/CMakeFiles/libavrdude.dir/linuxspi.c.o
[ 35%] Building C object src/CMakeFiles/libavrdude.dir/lists.c.o
[ 37%] Building C object src/CMakeFiles/libavrdude.dir/micronucleus.c.o
[ 38%] Building C object src/CMakeFiles/libavrdude.dir/par.c.o
[ 40%] Building C object src/CMakeFiles/libavrdude.dir/pgm.c.o
[ 41%] Building C object src/CMakeFiles/libavrdude.dir/pgm_type.c.o
[ 42%] Building C object src/CMakeFiles/libavrdude.dir/pickit2.c.o
[ 44%] Building C object src/CMakeFiles/libavrdude.dir/pindefs.c.o
[ 45%] Building C object src/CMakeFiles/libavrdude.dir/ppi.c.o
[ 47%] Building C object src/CMakeFiles/libavrdude.dir/ppiwin.c.o
[ 48%] Building C object src/CMakeFiles/libavrdude.dir/serbb_posix.c.o
[ 50%] Building C object src/CMakeFiles/libavrdude.dir/serbb_win32.c.o
[ 51%] Building C object src/CMakeFiles/libavrdude.dir/ser_avrdoper.c.o
[ 52%] Building C object src/CMakeFiles/libavrdude.dir/ser_posix.c.o
[ 54%] Building C object src/CMakeFiles/libavrdude.dir/ser_win32.c.o
[ 55%] Building C object src/CMakeFiles/libavrdude.dir/serialupdi.c.o
[ 57%] Building C object src/CMakeFiles/libavrdude.dir/stk500.c.o
[ 58%] Building C object src/CMakeFiles/libavrdude.dir/stk500v2.c.o
[ 60%] Building C object src/CMakeFiles/libavrdude.dir/stk500generic.c.o
[ 61%] Building C object src/CMakeFiles/libavrdude.dir/teensy.c.o
[ 62%] Building C object src/CMakeFiles/libavrdude.dir/updi_link.c.o
[ 64%] Building C object src/CMakeFiles/libavrdude.dir/updi_nvm.c.o
[ 65%] Building C object src/CMakeFiles/libavrdude.dir/updi_readwrite.c.o
[ 67%] Building C object src/CMakeFiles/libavrdude.dir/updi_state.c.o
[ 68%] Building C object src/CMakeFiles/libavrdude.dir/usbasp.c.o
[ 70%] Building C object src/CMakeFiles/libavrdude.dir/usb_hidapi.c.o
[ 71%] Building C object src/CMakeFiles/libavrdude.dir/usb_libusb.c.o
[ 72%] Building C object src/CMakeFiles/libavrdude.dir/usbtiny.c.o
[ 74%] Building C object src/CMakeFiles/libavrdude.dir/update.c.o
[ 75%] Building C object src/CMakeFiles/libavrdude.dir/wiring.c.o
[ 77%] Building C object src/CMakeFiles/libavrdude.dir/xbee.c.o
[ 78%] Building C object src/CMakeFiles/libavrdude.dir/__/lexer.c.o
[ 80%] Building C object src/CMakeFiles/libavrdude.dir/__/config_gram.c.o
[ 81%] Linking C static library libavrdude.a
[ 81%] Built target libavrdude
Scanning dependencies of target avrdude
[ 82%] Building C object src/CMakeFiles/avrdude.dir/main.c.o
[ 84%] Building C object src/CMakeFiles/avrdude.dir/term.c.o
[ 85%] Building C object src/CMakeFiles/avrdude.dir/developer_opts.c.o
[ 87%] Building C object src/CMakeFiles/avrdude.dir/whereami.c.o
[ 88%] Linking C executable avrdude
[ 88%] Built target avrdude
Scanning dependencies of target programmer_types.texi_target
[ 90%] Generating programmer_types.texi
[ 90%] Built target programmer_types.texi_target
Scanning dependencies of target parts.texi_target
[ 91%] Generating parts.texi
[ 91%] Built target parts.texi_target
Scanning dependencies of target programmers.texi_target
[ 92%] Generating programmers.texi
[ 92%] Built target programmers.texi_target
Scanning dependencies of target version.texi_target
[ 94%] Generating version.texi
84b0b96
[ 94%] Built target version.texi_target
Scanning dependencies of target doc_html_target
[ 95%] Generating avrdude.html
[ 95%] Built target doc_html_target
Scanning dependencies of target doc_pdf_target
[ 97%] Generating avrdude.pdf
This is pdfTeX, Version 3.14159265-2.6-1.40.20 (TeX Live 2019/Debian) (preloaded format=pdfetex)
 restricted \write18 enabled.
entering extended mode
... (skipped as it is very long) ...
[100%] Built target doc_ps_target
Scanning dependencies of target doc_target
[100%] Built target doc_target

mcuee@UbuntuSwift3:~/build/avr/avrdude_sbn$ ls ./build_linux/src/doc/ 
avrdude      avrdude.css  avrdude.ps    cmake_install.cmake  Makefile            programmer_types.texi
avrdude.aux  avrdude.dvi  avrdude.texi  gen_doc.sh           parts_comments.txt  tmp
avrdude.cp   avrdude.log  avrdude.toc   generator            parts.texi          version.texi
avrdude.cps  avrdude.pdf  CMakeFiles    gen_texi.sh          programmers.texi

[sbngross]

Thanks for testing and fixing.

-#!/bin/sh -e +#!/bin/bash -e

Ah I see what I did there. I wanted to use sh since it is most compatible AFAIK, but I used function which is bashism but is supported by zsh's bash emulator.

-git -C @CMAKE_SOURCE_DIR@ describe --tags +git -C @CMAKE_SOURCE_DIR@ describe --tags --always

Sorry that was moreless just test code for me and was destined to fail if one builts on a fork or from tarball. I shouldn't have pushed that. But good you found a way to fix this. I will add it.

I'm now working on the version stuff but I'm not sure how automake gets the 20220508 date. ~~There is no reference in the repo~~. EDIT: Turns out there is in configure.ac

But this is the date of the v7.0 release tag. What are the requirements here? Certainly it helps to have a local copy of the docs instead of online docs as stated above. But when built from git mtime is the date of the checkout and the version implies the documents are "newer" than the ones found online yet they are the same. I might overthink this so maybe I will in a first shot just add something that works