Building OpenOrbiter Documentation

[kuddel]

Hi there,
I am currently trying to build the Documentation of OpenOrbiter.
According to Martins post I've set ORBITER_MAKE_DOC to "ON" (in CMakePresets.json) and I think I have all the required tools[*].

But CMake complains with something like this:

1> [CMake] CMake Error at Src/Vessel/DeltaGlider/Help/CMakeLists.txt:20 (add_custom_command):
1> [CMake]   Error evaluating generator expression:
1> [CMake] 
1> [CMake]     $<TARGET_FILE:lua::exe>
1> [CMake] 
1> [CMake]   No target "lua::exe"
1> [CMake] 
1> [CMake]

Anyone?
By the way I am using Visual Studo 2019

[*] OpenOffice, LaTeX, Doxygen

 

[n72.75]

That's better than I get. For me it just doesn't build any documentation at all. (VS2022) I should have all the dependencies.

 

[Sword7]

I have the same problem when I am trying to build documents on Visual Studio Code (on Linux). I installed full Tex-Live package. I am learning how to build documents from doxygen files, etc.

 

[jarmonik]

We would need some kind of record for a things that are new and require further documentation. I have already forgotten probably more than a half of the things that are new and undocumented.

I have never tried to build the Orbiter with documentation.

 

[kuddel]

Looking into CMakeLists.txt (The main one in root directory):


Is this valid syntax? I mean line 103 ... Lines 86 & 87 have similar entries, but not an extra double-colon ("::").

And by the way, where is LUA_DIR defined?

 

[Urwumpe]

Is this valid syntax? I mean line 103 ... Lines 86 & 87 have similar entries, but not an extra double-colon ("::").

Yes, because Lua is an imported target and the expression itself a generator:

cmake-generator-expressions(7) — CMake 3.29.1 Documentation

cmake.org

Importing and Exporting Guide — CMake 3.29.1 Documentation

cmake.org

Short: It looks for the path to the binary file for the target "lua::exe" which is a subproject of "lua". "LUA_DIR" should be defined by the package module for Lua (FindLua)

FindLua — CMake 3.28.1 Documentation

cmake.org

 

[GLS]

We would need some kind of record for a things that are new and require further documentation.

The PRs should aready update the documentation as needed.

 

[kuddel]

The PRs should aready update the documentation as needed.

I am not sure I understand that correctly.
Accepted (merged) Pull Requests do update a document somewhere?
Or do you mean: It is possible to find that information by looking at (closed) PRs.

 

[GLS]

I am not sure I understand that correctly.
Accepted (merged) Pull Requests do update a document somewhere?
Or do you mean: It is possible to find that information by looking at (closed) PRs.

(for "regular" documentation)
Say I make a PR adding a new surface base building type. I should also have to update the document the lists those buildings and their parameters (one of the pdfs does has that info). Who better to document a feature than its author?

(for a release change log)
Probably a +/- manually curated list should be produced, based on git logs.

 

[n72.75]

(for "regular" documentation)
Say I make a PR adding a new surface base building type. I should also have to update the document the lists those buildings and their parameters (one of the pdfs does has that info). Who better to document a feature than its author?

(for a release change log)
Probably a +/- manually curated list should be produced, based on git logs.

The issue is not "documenting new features". The issue is that the documents themselves LaTeX/Doxgen/etc don't get created by the build process.

I don't know if we've added a lot of API features, but the two I've worked on:

New airfoil: has Doxgen comments for the API reference document.

New Gravity model: updated api referenc, credits document, and at Martin's request the Non-spherical gravity technote.

I 100% agree that authors of new features should be the ones to document them. I don't see how else that could work. But what were looking at here is an issue with the build process for documents themselves.

I believe the packaged Orbiter builds on Github also have this problem, so maybe it's a cmake issue?

 

[kuddel]

(for "regular" documentation)
Say I make a PR adding a new surface base building type. I should also have to update the document the lists those buildings and their parameters (one of the pdfs does has that info). Who better to document a feature than its author?

Ah, I see. Yes that is absolutely right! You mean Doc\Orbiter.odt , right?

(for a release change log)
Probably a +/- manually curated list should be produced, based on git logs.

Yes, a history.txt ore similar would also help when updating Doc\Orbiter.odt.

The issue is not "documenting new features". The issue is that the documents themselves LaTeX/Doxgen/etc don't get created by the build process.
[...]
I believe the packaged Orbiter builds on Github also have this problem, so maybe it's a cmake issue?

Yes as Martin explained here the CI currently does not do this.

 

[kuddel]

A general documenting question:
Has anyone been able to build the documentation?
I am still struggeling to get it working
The README.md says:

Some configuration caveats:

• If you are using the Ninja generator (default for the VS built-in CMake), you may also need vspkg to configure the VS toolset.
• If you are using the VS2019 generator, you may need to set up Visual Studio to use only a single thread for the build. This is because some of the build tools (especially those for generating the Orbiter documentation) are not threadsafe, and the VS2019 generator doesn't understand the CMake JOB_POOL directive.

Orbiter is a 32-bit application. Be sure to configure vspkg and CMake accordingly.

If you want to build the documentation, you need a few additional tools:

• a filter to convert ODT and DOC sources to PDF, such as LibreOffice.
• a LaTeX compiler suite such as MiKTeX.
• Doxygen for building the source-level documentation for developers.

I think I need that vspkg thing (and do something with that?), as all the other requirements I do fullfill (I believe )

Can anyone possibly help?

 

[Urwumpe]

I think I need that vspkg thing (and do something with that?), as all the other requirements I do fullfill (I believe )

If it is properly installed, it automatically downloads all dependencies for Orbiter on your computer while CMake configures the build scripts.

 

[kuddel]

Aha! Thanks for the info.
So "just" clone & build vspkg (as noted here I guess...) and re-try to generate docs in OpenOrbiter...
I will try...

 

[Urwumpe]

Aha! Thanks for the info.
So "just" clone & build vspkg (as noted here I guess...) and re-try to generate docs in OpenOrbiter...
I will try...

AFAIR, you also need to set some CMake, Visual Studio or environment variables. But the github page for vspkg should contain all the info you need.

(Oh I see, they automated the step! Nevermind and thank you vspkg team)

 

[kuddel]

Hmmm no change (except for another useless 97,5 MB of "tooling")

 

[Urwumpe]

Hmmm no change (except for another useless 97,5 MB of "tooling")

Still the same error? Did you set it to 32 bit?

 

[kuddel]

32 bit ... you mean when building OpenOrbiter, right? As I don't know how to build vspkg as 32 bit.

Let me try that...

 

[kuddel]

No luck

These error appear as soon as "the cache" or whatever that is is configured...

1> CMake generation started for configuration: 'windows-x86-release'.
 ...
1> [CMake] CMake Error at Src/Vessel/DeltaGlider/Help/CMakeLists.txt:20 (add_custom_command):
1> [CMake]   Error evaluating generator expression:
1> [CMake]
1> [CMake]     $<TARGET_FILE:lua::exe>
1> [CMake]
1> [CMake]   No target "lua::exe"
1> [CMake]

Even CMakes list of my environment (too much information ) also has "lots of Lua"

• in Path : "C:\Program Files (x86)\Lua\5.1;C:\Program Files (x86)\Lua\5.1\clibs;"
• in __VSCMD_PREINIT_PATH : "C:\Program Files (x86)\Lua\5.1;C:\Program Files (x86)\Lua\5.1\clibs"
• in LUA_DEV : "C:\Program Files (x86)\Lua\5.1"
• and in LUA_PATH : ";;C:\Program Files (x86)\Lua\5.1\lua\?.luac"

1> Environment settings:
1>     CommandPromptType=Cross
1>     DevEnvDir=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\
1>     ExtensionSdkDir=C:\Program Files (x86)\Microsoft SDKs\Windows Kits\10\ExtensionSDKs
1>     Framework40Version=v4.0
1>     FrameworkDir=C:\Windows\Microsoft.NET\Framework64\
1>     FrameworkDir32=C:\Windows\Microsoft.NET\Framework\
1>     FrameworkDir64=C:\Windows\Microsoft.NET\Framework64\
1>     FrameworkVersion=v4.0.30319
1>     FrameworkVersion32=v4.0.30319
1>     FrameworkVersion64=v4.0.30319
1>     HTMLHelpDir=C:\Program Files (x86)\HTML Help Workshop
1>     INCLUDE=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\ATLMFC\include;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\include;C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\include\um;C:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\ucrt;C:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\shared;C:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\um;C:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\winrt;C:\Program Files (x86)\Windows Kits\10\include\10.0.19041.0\cppwinrt
1>     LIB=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\ATLMFC\lib\x86;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\lib\x86;C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\lib\um\x86;C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\ucrt\x86;C:\Program Files (x86)\Windows Kits\10\lib\10.0.19041.0\um\x86
1>     LIBPATH=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\ATLMFC\lib\x86;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\lib\x86;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\lib\x86\store\references;C:\Program Files (x86)\Windows Kits\10\UnionMetadata\10.0.19041.0;C:\Program Files (x86)\Windows Kits\10\References\10.0.19041.0;C:\Windows\Microsoft.NET\Framework64\v4.0.30319
1>     NETFXSDKDir=C:\Program Files (x86)\Windows Kits\NETFXSDK\4.8\
1>     Path=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\\Extensions\Microsoft\IntelliCode\CLI;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\bin\HostX64\x86;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\bin\HostX64\x64;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\VC\VCPackages;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TestWindow;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\bin\Roslyn;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Team Tools\Performance Tools;C:\Program Files (x86)\Microsoft Visual Studio\Shared\Common\VSPerfCollectionTools\vs2019\;C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\x64\;C:\Program Files (x86)\HTML Help Workshop;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\devinit;C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64;C:\Program Files (x86)\Windows Kits\10\bin\x64;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\\MSBuild\Current\Bin;C:\Windows\Microsoft.NET\Framework64\v4.0.30319;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\;C:\Program Files\Microsoft\jdk-17.0.5.8-hotspot\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\Program Files\Python27;C:\Program Files\Python27\Scripts;C:\Program Files\Python311;C:\Program Files\Python311\Scripts;C:\Program Files\ImageMagick;C:\Program Files\doxygen\bin;C:\WINDOWS\System32\OpenSSH\;C:\Program Files (x86)\Lua\5.1;C:\Program Files (x86)\Lua\5.1\clibs;C:\Program Files\dotnet\;C:\Program Files (x86)\Plantronics\Spokes3G\;C:\Program Files\TortoiseSVN\bin;C:\Program Files\Git\cmd;C:\Program Files\TortoiseGit\bin;C:\Program Files\MiKTeX\miktex\bin\x64\;C:\Users\kuddel\AppData\Roaming\Python\Scripts;C:\Users\kuddel\AppData\Local\Microsoft\WindowsApps;C:\Users\kuddel\AppData\Local\GitHubDesktop\bin;%USERPROFILE%\AppData\Local\Microsoft\WindowsApps;;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin;C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\Ninja
1>     PreferredToolArchitecture=x64
1>     PROMPT=$P$G
1>     UCRTVersion=10.0.19041.0
1>     UniversalCRTSdkDir=C:\Program Files (x86)\Windows Kits\10\
1>     VCIDEInstallDir=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\VC\
1>     VCINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\
1>     VCToolsInstallDir=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\
1>     VCToolsRedistDir=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Redist\MSVC\14.29.30133\
1>     VCToolsVersion=14.29.30133
1>     VS160COMNTOOLS=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\
1>     VSCMD_ARG_app_plat=Desktop
1>     VSCMD_ARG_HOST_ARCH=x64
1>     VSCMD_ARG_no_logo=1
1>     VSCMD_ARG_TGT_ARCH=x86
1>     VSCMD_DEBUG=5
1>     VSCMD_VER=16.11.33
1>     VSINSTALLDIR=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\
1>     WindowsLibPath=C:\Program Files (x86)\Windows Kits\10\UnionMetadata\10.0.19041.0;C:\Program Files (x86)\Windows Kits\10\References\10.0.19041.0
1>     WindowsSdkBinPath=C:\Program Files (x86)\Windows Kits\10\bin\
1>     WindowsSdkDir=C:\Program Files (x86)\Windows Kits\10\
1>     WindowsSDKLibVersion=10.0.19041.0\
1>     WindowsSdkVerBinPath=C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\
1>     WindowsSDKVersion=10.0.19041.0\
1>     WindowsSDK_ExecutablePath_x64=C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\x64\
1>     WindowsSDK_ExecutablePath_x86=C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\
1>     __devinit_path=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\Tools\devinit\devinit.exe
1>     __DOTNET_ADD_32BIT=1
1>     __DOTNET_ADD_64BIT=1
1>     __DOTNET_PREFERRED_BITNESS=64
1>     __VSCMD_PREINIT_PATH=C:\Program Files\Microsoft\jdk-17.0.5.8-hotspot\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem;C:\WINDOWS\System32\WindowsPowerShell\v1.0\;C:\Program Files\Python27;C:\Program Files\Python27\Scripts;C:\Program Files\Python311;C:\Program Files\Python311\Scripts;C:\Program Files\ImageMagick;C:\Program Files\doxygen\bin;C:\WINDOWS\System32\OpenSSH\;C:\Program Files (x86)\Lua\5.1;C:\Program Files (x86)\Lua\5.1\clibs;C:\Program Files\dotnet\;C:\Program Files (x86)\Plantronics\Spokes3G\;C:\Program Files\TortoiseSVN\bin;C:\Program Files\Git\cmd;C:\Program Files\TortoiseGit\bin;C:\Program Files\MiKTeX\miktex\bin\x64\;C:\Users\kuddel\AppData\Roaming\Python\Scripts;C:\Users\kuddel\AppData\Local\Microsoft\WindowsApps;C:\Users\kuddel\AppData\Local\GitHubDesktop\bin;%USERPROFILE%\AppData\Local\Microsoft\WindowsApps;
1>     __VSCMD_script_err_count=0
1>     CMAKE_INSTALL_PREFIX=D:/Programme/Orbiter/orbiter-git-schnepe2/out/install/windows-x86-release
1>     VCPKG_FEATURE_FLAGS=manifests,versions,binarycaching,registries
1>     PROCESSOR_ARCHITEW6432=AMD64
1>     COMMANDER_PATH=C:\Program Files\totalcmd
1>     COMPUTERNAME=KUDDEL-3
1>     DriverData=C:\Windows\System32\Drivers\DriverData
1>     LUA_DEV=C:\Program Files (x86)\Lua\5.1
1>     OneDrive=C:\Users\kuddel\OneDrive
1>     HOMEPATH=\Users\kuddel
1>     SESSIONNAME=Console
1>     VisualStudioEdition=Microsoft Visual Studio Community 2019
1>     ServiceHubLogSessionKey=517FAD54
1>     SignInWithHomeTenantOnly=False
1>     PROCESSOR_REVISION=4e03
1>     USERDOMAIN_ROAMINGPROFILE=KUDDEL-3
1>     PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.py;.pyw;.wlua;.lexe
1>     PkgDefApplicationConfigFile=C:\Users\kuddel\AppData\Local\Microsoft\VisualStudio\16.0_5ec8e047\devenv.exe.config
1>     TMP=C:\Users\kuddel\AppData\Local\Temp
1>     TEMP=C:\Users\kuddel\AppData\Local\Temp
1>     LOCALAPPDATA=C:\Users\kuddel\AppData\Local
1>     PUBLIC=C:\Users\Public
1>     COMMANDER_EXE=C:\Program Files\totalcmd\TOTALCMD64.EXE
1>     VSAPPIDNAME=devenv.exe
1>     JAVA_HOME=C:\Program Files\Microsoft\jdk-17.0.5.8-hotspot\
1>     USERDOMAIN=KUDDEL-3
1>     COMMANDER_INSTANCE=1
1>     KICAD_PTEMPLATES=C:\Program Files\KiCad\share\kicad\template
1>     PROCESSOR_LEVEL=6
1>     PROCESSOR_IDENTIFIER=Intel64 Family 6 Model 78 Stepping 3, GenuineIntel
1>     ForceIdentityAuthenticationType=Embedded
1>     ProgramFiles(x86)=C:\Program Files (x86)
1>     NUMBER_OF_PROCESSORS=4
1>     FPS_BROWSER_USER_PROFILE_STRING=Default
1>     CommonProgramFiles=C:\Program Files (x86)\Common Files
1>     VS140COMNTOOLS=C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\
1>     VisualStudioDir=D:\Users\kuddel\Documents\Visual Studio 2019
1>     ProgramData=C:\ProgramData
1>     ProgramW6432=C:\Program Files
1>     ProgramFiles=C:\Program Files (x86)
1>     VSSKUEDITION=Community
1>     ThreadedWaitDialogDpiContext=-4
1>     SystemRoot=C:\WINDOWS
1>     LUA_PATH=;;C:\Program Files (x86)\Lua\5.1\lua\?.luac
1>     VSAPPIDDIR=C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\
1>     COMMANDER_SESSIONNAME=user
1>     VisualStudioVersion=16.0
1>     CommonProgramW6432=C:\Program Files\Common Files
1>     ZES_ENABLE_SYSMAN=1
1>     LOGONSERVER=\\KUDDEL-3
1>     USERPROFILE=C:\Users\kuddel
1>     MSBuildLoadMicrosoftTargetsReadOnly=true
1>     QtMsBuild=C:\Users\kuddel\AppData\Local\QtMsBuild
1>     VSLANG=1033
1>     CommonProgramFiles(x86)=C:\Program Files (x86)\Common Files
1>     COMMANDER_INI=C:\Users\kuddel\AppData\Roaming\GHISLER\wincmd.ini
1>     APPDATA=C:\Users\kuddel\AppData\Roaming
1>     HOMEDRIVE=C:
1>     COMMANDER_DRIVE=C:
1>     PSModulePath=C:\Program Files\WindowsPowerShell\Modules;C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules
1>     USERNAME=kuddel
1>     DXSDK_DIR=C:\Program Files (x86)\Microsoft DirectX SDK (June 2010)\
1>     FPS_BROWSER_APP_PROFILE_STRING=Internet Explorer
1>     PROCESSOR_ARCHITECTURE=x86
1>     OS=Windows_NT
1>     ComSpec=C:\WINDOWS\system32\cmd.exe
1>     SystemDrive=C:
1>     windir=C:\WINDOWS
1>     ALLUSERSPROFILE=C:\ProgramData

 

[Urwumpe]

Ahhhhhh... how did you include Lua, as subproject as expected? Lua expects that a target is defined, a target Lua and that has a subproject with the target exe.

See here:

orbiter/Extern/CMakeLists.txt at main · orbitersim/orbiter

Open-source repository of Orbiter Space Flight Simulator - orbitersim/orbiter

github.com