#LyX 2.2 created this file. For more info see http://www.lyx.org/
-\lyxformat 499
+\lyxformat 501
\begin_document
\begin_header
\origin /systemlyxdir/doc/
-\textclass scrbook
-\options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
+\textclass scrartcl
+\options BCOR8mm,captions=tableheading
\use_default_options false
\begin_modules
logicalmkup
-theorems-ams
-theorems-ams-extended
-multicol
-shapepar
\end_modules
\maintain_unincluded_children false
\begin_local_layout
\language_package default
\inputencoding auto
\fontencoding global
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_math auto
+\font_roman "lmodern" "default"
+\font_sans "lmss" "default"
+\font_typewriter "lmtt" "default"
+\font_math "auto" "auto"
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
+\font_sf_scale 100 100
+\font_tt_scale 100 100
\graphics default
\default_output_format default
\output_sync 0
\end_layout
-\begin_layout Chapter
+\begin_layout Section
Introduction
\end_layout
development, you may find some interesting information.
\end_layout
-\begin_layout Chapter
+\begin_layout Section
File formats
\end_layout
tion.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
File Format Numbers
\end_layout
-\begin_layout Section
+\begin_layout Subsection
When is an update of the .lyx file format number needed?
\begin_inset CommandInset label
LatexCommand label
If you are still unsure, please ask on the development list.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
How to update the file format number of .lyx files
\end_layout
\begin_layout Enumerate
It would be nice if you could create a .lyx test file which contains instances
of all changed or added features.
- This could then be used to test lyxl2yx and tex2lyx.
+ This could then be used to test lyx2lyx and tex2lyx.
Unfortunately it has not yet been decided how to collect such examples,
so please ask on the development list if you want to create one.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
Backporting new styles to the stable version
\end_layout
version.
\end_layout
-\begin_layout Chapter
+\begin_layout Standard
+\begin_inset Newpage newpage
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
Tests
\end_layout
easily, and some tests of this kind exist.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
\SpecialChar LyX
tests
\end_layout
source code distribution.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Running the tests
\end_layout
\begin_layout Standard
-The \SpecialChar LyX
+cmake is required to run the \SpecialChar LyX
+ tests, running them is not implemented for
+ autotools.
+ The \SpecialChar LyX
tests can be run by the commands
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-make test
+ctest
\end_layout
\end_inset
- (cmake) in the
+ (all platforms) or
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-autotests
+make test
\end_layout
\end_inset
- subfolder of the build directory.
-\begin_inset Note Note
-status open
+ (when using a make based build system and not MSVC) in the
+\begin_inset Flex Code
+status collapsed
\begin_layout Plain Layout
-FIXME: Is this possible with autotools?
+autotests
\end_layout
\end_inset
-
+ subfolder of the build directory.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
tex2lyx tests
\end_layout
This may be useful for roundtrip comparisons.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Running the tests
\end_layout
\begin_layout Standard
-The tex2lyx tests can be run by the commands
+The tex2lyx tests can be run in several ways.
+ When in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+src/tex2lyx
+\end_layout
+
+\end_inset
+
+ subfolder of the build directory, the commands
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest
+\end_layout
+
+\end_inset
+
+ (cmake, all platforms),
\begin_inset Flex Code
status collapsed
\end_inset
- (cmake) or
+ (cmake, when using a make based build system and not MSVC) or
\begin_inset Flex Code
status collapsed
\end_inset
- (autotools) in the
+ (autotools) will run the tex2lyx tests.
+ Alternatively, in the root of the build directory, the command
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
-src/tex2lyx
+ctest -R tex2lyx
\end_layout
\end_inset
- subfolder of the build directory.
+ runs all tests whose names match the regex
+\begin_inset Quotes eld
+\end_inset
+
+tex2lyx
+\begin_inset Quotes erd
+\end_inset
+
+.
+ Another way to run the tex2lyx tests in the root build directory is to
+ instead use the command
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L '(cmplyx|roundtrip)'
+\end_layout
+
+\end_inset
+
+, which runs all tests categorized with the label
+\begin_inset Quotes eld
+\end_inset
+
+roundtrip
+\begin_inset Quotes erd
+\end_inset
+
+ or
+\begin_inset Quotes eld
+\end_inset
+
+cmplyx
+\begin_inset Quotes erd
+\end_inset
+
+.
If a test fails, the differences between the expected and actual results
are output in unified diff format.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Updating test references
\begin_inset CommandInset label
LatexCommand label
\end_inset
- subdirectory of the build directory
+ subdirectory of the build directory.
\begin_inset Foot
status collapsed
\end_inset
+ On Windows do the following:
+\end_layout
+
+\begin_layout Itemize
+Assure that the path to the python.exe is in your system PATH variable.
+\end_layout
+
+\begin_layout Itemize
+Double-click on the file
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+updatetex2lyxtests.vcxproj
+\end_layout
+
+\end_inset
+
+ in the build directory or in the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+src/tex2lyx/test
+\end_layout
+
+\end_inset
+
+ subdirectory of your build directory.
+\end_layout
+
+\begin_layout Itemize
+In the appearing MSVC program right-click on the project
+\family sans
+updatetex2lyxtests
+\family default
+ in the project explorer and chose
+\family sans
+Create
+\family default
.
- For convenience, these commands also produce re-exported roundtrip .lyx.tex
+\end_layout
+
+\begin_layout Standard
+For convenience, these commands also produce re-exported roundtrip .lyx.tex
files.
Please examine the changed output carefully before committing the changed
files to the repository: Since the test machinery does not do a roundtrip
regarding insignificant whitespace and line breaks.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Adding a new test
\end_layout
list and ask for committing if you do not have commit rights.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
Export tests
\end_layout
e it is important to keep them up-to-date and understand how they work.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Expectations of LyX developers
\end_layout
.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Configuring the tests
\end_layout
).
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
Running the tests
\end_layout
\begin_layout Standard
-To run all of the export tests, in the build directory simply run the command
-
+To run all tests, in the build directory simply run the command
\begin_inset Flex Code
status collapsed
\end_inset
is a regular expression that matches test names.
+ To run only the export tests, you can use
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L export
+\end_layout
+
+\end_inset
+
+.
+ For the list of test categories available in addition to
+\begin_inset Quotes eld
+\end_inset
+
+export
+\begin_inset Quotes erd
+\end_inset
+
+, run
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest \SpecialChar nobreakdash
+\SpecialChar nobreakdash
+print-labels
+\end_layout
+
+\end_inset
+
+.
It is often useful to list the tests without running them (e.g.
if you want to know how many tests there are or whether your
\begin_inset Flex Code
status collapsed
\begin_layout Plain Layout
---show-only
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+show-only
\end_layout
\end_inset
status collapsed
\begin_layout Plain Layout
---parallel <jobs>
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+parallel <jobs>
\end_layout
\end_inset
status collapsed
\begin_layout Plain Layout
-ctest -
-\begin_inset ERT
-status open
-
-\begin_layout Plain Layout
-
-{}
-\end_layout
-
-\end_inset
-
--rerun-failed
+ctest \SpecialChar nobreakdash
+\SpecialChar nobreakdash
+rerun-failed
\end_layout
\end_inset
status collapsed
\begin_layout Plain Layout
---timeout <seconds>
+\SpecialChar nobreakdash
+\SpecialChar nobreakdash
+timeout <seconds>
\end_layout
\end_inset
command.
\end_layout
-\begin_layout Subsection
+\begin_layout Subsubsection
\begin_inset CommandInset label
LatexCommand label
name "subsec:Interpreting-export-tests"
A test can fail for several reasons, not all of them bad.
\end_layout
-\begin_layout Itemize
+\begin_layout Enumerate
The .lyx file could have been added recently and some formats are not expected
to work well.
\end_layout
-\begin_layout Itemize
+\begin_layout Enumerate
A dependency is not met (e.g.
the LaTeX class file).
One hint that this is the case is that the corresponding
test will likely also fail.
\end_layout
-\begin_layout Itemize
+\begin_layout Enumerate
An export that previously failed to compile now compiles.
\end_layout
-\begin_layout Itemize
+\begin_layout Enumerate
An external dependency was updated (e.g.
TeX Live).
\end_layout
-\begin_layout Itemize
+\begin_layout Enumerate
A recent code change introduced a bug.
\end_layout
+\begin_layout Enumerate
+\begin_inset CommandInset label
+LatexCommand label
+name "enu:exposed"
+
+\end_inset
+
+A change in a document exposed the incompatibility of that class with an
+ export format (e.g.
+ LuaTeX).
+\end_layout
+
\begin_layout Standard
Because the .lyx files are exported in several formats, it is not surprising
that many of the exports fail.
tests.
If the export actually succeeds, then the test will fail.
- The purpose of this failure is to get your attentions—something has changed,
+ The purpose of this failure is to get your attention—something has changed,
possibly for the better.
\end_layout
\end_inset
.
+ It is possible that an export goes from succeeding to failing just because
+ the document was changed and the document was never expected to work with
+ a certain export format in the first case.
+ Once this is confirmed to be the situation, the test can be inverted.
+\end_layout
+
+\begin_layout Standard
+A good question is why do we enable the tests for non-default formats? The
+ answer is that if a non-default route is broken it is often because a bug
+ was introduced in LyX and not because a document-specific change was made
+ that is not supported by the route.
+ In other words, there is a high signal/noise ratio in the export tests
+ for the non-default formats.
+
\end_layout
\begin_layout Standard
file lists the times that it took to run the tests.
\end_layout
-\begin_layout Section
+\begin_layout Subsubsection
+Suspended tests
+\end_layout
+
+\begin_layout Standard
+Some inverted tests are 'suspended'.
+ This means, they are not executed using
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L export
+\end_layout
+
+\end_inset
+
+ or
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+ctest -L reverted
+\end_layout
+
+\end_inset
+
+.
+ From time to time they still have to be checked.
+\end_layout
+
+\begin_layout Standard
+These tests are suspended, because they fail for known reasons which cannot
+ ATM be resolved.
+ But it is expected the reason might disappear in the future.
+ Be it new TL or better handling in \SpecialChar LyX
+.
+\end_layout
+
+\begin_layout Standard
+For ctest commands without the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+-L
+\end_layout
+
+\end_inset
+
+ parameter nothing changes.
+ Suspended or not, tests will be executed depending only on the regexes
+ parameters given to the ctest command.
+\end_layout
+
+\begin_layout Subsection
check_load tests
\end_layout
.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
URL tests
\end_layout
\begin_layout Standard
-These tests are extremely fragile and a failed URL test should not be taken
- too seriously.
- They are useful for finding broken links in our documentation files.
- These must be enabled at configure.
+The URL tests are enabled with the
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+-DLYX_ENABLE_URLTESTS=ON
+\end_layout
+
+\end_inset
+
+ CMake flag and are useful for finding broken links in our documentation
+ files.
+ If a URL test fails, to see which link in particular was reported as broken,
+ see the output in
+\begin_inset Flex Code
+status collapsed
+
+\begin_layout Plain Layout
+LastTest.log
\end_layout
-\begin_layout Chapter
+\end_inset
+
+.
+ These tests are extremely fragile (e.g.
+ a test can depend on your Internet connection) and a failed URL test should
+ not be taken too seriously.
+\end_layout
+
+\begin_layout Section
Development policies
\end_layout
.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
When to set a fixed milestone?
\end_layout
For all other bugs, do not set a milestone at all.
\end_layout
-\begin_layout Section
+\begin_layout Subsection
Can we add rc entries in stable branch?
\end_layout
We are supposed to increase the prefs2prefs version number with such things.
\end_layout
-\begin_layout Chapter
+\begin_layout Section
Documentation policies
\end_layout
projects / lyx.git / blobdiff