[utilities/kate] /: Update the build plugin documentation
Kåre Särs <[email protected]>
| Newsgroups | gmane.comp.kde.cvs,gmane.comp.kde.doc |
|---|---|
| Message-ID | <[email protected]> |
Git commit e729fd0a08f8b5460b6c08addb75748ee615b285 by Kåre Särs.
Committed on 14/01/2025 at 06:28.
Pushed by sars into branch 'master'.
Update the build plugin documentation
Add "insert path" also to "Run Command"
BUG: 497961
M +8 -8 addons/katebuild-plugin/TargetHtmlDelegate.cpp
M +1 -1 addons/katebuild-plugin/TargetModel.cpp
M +1 -0 addons/katebuild-plugin/UrlInserter.h
M +- -- doc/kate/build-output.png
A +- -- doc/kate/media-playback-start-22.png
M +83 -55 doc/kate/plugins.docbook
A +- -- doc/kate/run-build-22.png
https://invent.kde.org/utilities/kate/-/commit/e729fd0a08f8b5460b6c08addb75748ee615b285
diff --git a/addons/katebuild-plugin/TargetHtmlDelegate.cpp b/addons/katebuild-plugin/TargetHtmlDelegate.cpp
index acab418165..65f145923e 100644
--- a/addons/katebuild-plugin/TargetHtmlDelegate.cpp
+++ b/addons/katebuild-plugin/TargetHtmlDelegate.cpp
@@ -50,7 +50,7 @@ void TargetHtmlDelegate::paint(QPainter *painter, const QStyleOptionViewItem &op
if (index.column() == 0) {
str = i18nc("T as in Target set", "<B>T:</B> %1", index.data().toString().toHtmlEscaped());
} else if (index.column() == 1) {
- str = i18nc("D as in working Directory", "<B>Dir:</B> %1", index.data().toString().toHtmlEscaped());
+ str = i18nc("Dir as in working Directory", "<B>Dir:</B> %1", index.data().toString().toHtmlEscaped());
}
} else {
str = index.data().toString().toHtmlEscaped();
@@ -102,7 +102,7 @@ QWidget *TargetHtmlDelegate::createEditor(QWidget *dparent, const QStyleOptionVi
requester->setReplace(true);
editor = requester;
editor->setToolTip(i18n("Leave empty to use the directory of the current document.\nAdd search directories by adding paths separated by ';'"));
- } else if (index.column() == 1) {
+ } else if (index.column() == 1 || index.column() == 2) {
auto *urlEditor = new UrlInserter(parent()->property("docUrl").toUrl(), dparent);
editor = urlEditor;
int const rowtype = index.data(TargetModel::RowTypeRole).toInt();
@@ -132,13 +132,13 @@ void TargetHtmlDelegate::setEditorData(QWidget *editor, const QModelIndex &index
{
QString value = index.model()->data(index, Qt::EditRole).toString();
- if (index.column() == 1) {
- auto *ledit = static_cast<UrlInserter *>(editor);
+ if (index.column() == 1 || index.column() == 2) {
+ auto *ledit = qobject_cast<UrlInserter *>(editor);
if (ledit) {
ledit->lineEdit()->setText(value);
}
} else {
- auto *ledit = static_cast<QLineEdit *>(editor);
+ auto *ledit = qobject_cast<QLineEdit *>(editor);
if (ledit) {
ledit->setText(value);
}
@@ -148,11 +148,11 @@ void TargetHtmlDelegate::setEditorData(QWidget *editor, const QModelIndex &index
void TargetHtmlDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const
{
QString value;
- if (index.column() == 1) {
- auto *ledit = static_cast<UrlInserter *>(editor);
+ if (index.column() == 1 || index.column() == 2) {
+ auto *ledit = qobject_cast<UrlInserter *>(editor);
value = ledit->lineEdit()->text();
} else {
- auto *ledit = static_cast<QLineEdit *>(editor);
+ auto *ledit = qobject_cast<QLineEdit *>(editor);
value = ledit->text();
}
model->setData(index, value, Qt::EditRole);
diff --git a/addons/katebuild-plugin/TargetModel.cpp b/addons/katebuild-plugin/TargetModel.cpp
index 60bb8eb54b..864b5544bb 100644
--- a/addons/katebuild-plugin/TargetModel.cpp
+++ b/addons/katebuild-plugin/TargetModel.cpp
@@ -631,7 +631,7 @@ QVariant TargetModel::headerData(int section, Qt::Orientation orientation, int r
return i18n("Command/Target-set Name");
}
if (section == 1) {
- return i18n("Working Directory / Command");
+ return i18n("Build Command / Working Directory");
}
if (section == 2) {
return i18n("Run Command");
diff --git a/addons/katebuild-plugin/UrlInserter.h b/addons/katebuild-plugin/UrlInserter.h
index d9ba437e12..e07eb50971 100644
--- a/addons/katebuild-plugin/UrlInserter.h
+++ b/addons/katebuild-plugin/UrlInserter.h
@@ -14,6 +14,7 @@
class UrlInserter : public QWidget
{
+ Q_OBJECT
public:
UrlInserter(const QUrl &startUrl, QWidget *parent);
QLineEdit *lineEdit()
diff --git a/doc/kate/build-output.png b/doc/kate/build-output.png
index e34fdb1f5f..3789572994 100644
Binary files a/doc/kate/build-output.png and b/doc/kate/build-output.png differ
diff --git a/doc/kate/media-playback-start-22.png b/doc/kate/media-playback-start-22.png
new file mode 100644
index 0000000000..4e24aa210e
Binary files /dev/null and b/doc/kate/media-playback-start-22.png differ
diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
index ae2d71e273..c28250c3e6 100644
--- a/doc/kate/plugins.docbook
+++ b/doc/kate/plugins.docbook
@@ -584,17 +584,21 @@ When indexing is finished, open the toolview <guilabel>Backtrace Browser</guilab
<title>Introduction</title>
<para>The Build plugin allows you to run actions like build, clean and compile
-on a project.</para>
+on a project. You can also automatically run the generated applications. The plugin basically
+gives you a way to configure sets of commands to run and it can parse the output for links to
+files and specific lines and columns in those files. So even if the plugin is originally created
+for compiling C/C++ and mostly tested with it, the plugin can also be useful for other
+purposes and languages.</para>
</sect2>
<sect2 id="build-using">
<title>Using the Build Plugin</title>
-<para>The Build plugin adds a <guilabel>Build Output</guilabel> tool view at the
-bottom and a <guimenu>Build</guimenu> menu on the menubar. The tool view can be used to configure
-build target settings, while the menu can be used to perform build, clean and
-compile actions.</para>
+<para>The Build plugin adds a <guilabel>Build</guilabel> tool view at the
+bottom and a <guimenu>Build</guimenu> menu on the menu bar. The tool view can be used to select and
+configure build targets, while the menu and it's shortcuts can be used to select and execute the
+configured shell commands.</para>
<screenshot id="screenshot-build-output">
<screeninfo>Build Output</screeninfo>
@@ -603,7 +607,7 @@ compile actions.</para>
</mediaobject>
</screenshot>
-<para>The <guilabel>Build Output</guilabel> tool view has two tabs:</para>
+<para>The <guilabel>Build</guilabel> tool view has two static tabs:</para>
<itemizedlist>
<listitem><para><guilabel>Target Settings</guilabel></para></listitem>
@@ -613,52 +617,63 @@ compile actions.</para>
<sect3 id="build-using-target-settings">
<title>Target Settings tab</title>
-<para>The target settings tab can be used to configure various build targets and define targets sets.</para>
+<para>The target settings tab can be used to configure various build targets and define target sets.</para>
-<para>To change the names or commands double click on the entries in the table and use the
-dropdown box to select the active target set. Use the checkbox in front of each target to define a default.</para>
+<para>A target-set is a group of commands that can be run in a specified working directory.
+Target sets can be added under either <guilabel>Projects</guilabel> or <guilabel>Session</guilabel>.
+The custom target-sets added under <guilabel>Projects</guilabel> are stored in a <guilabel>.kateproject.build</guilabel>
+file in the project root directory and are restored when the project is re-opened. The target-sets added
+under <guilabel>Session</guilabel> are stored in the current Kate session configuration.</para>
-<para>A new target set contains several configuration options:</para>
+<para>The first row, in a target-set, contains a name for the set in column one, and in column two we
+ have the directory where the commands should be executed. On each following row, we have
+ a name for the command in column one, a build command in column two and a run command in column three.
+ To edit one of these, double-click on the entry or use the edit shortcut (often F2).</para>
<variablelist>
<varlistentry>
<term><guilabel>Working Directory</guilabel></term>
-<listitem><para>You can set the path to the project here. Leave this empty to
-use the directory the current document is located in.</para></listitem>
+<listitem><para>The second column of the first row in a target-set, is used to configure the
+working directory used for compiling and running commands. If the project plugin is enabled, the
+working directory string can also contain placeholders for the project base directory path:
+<guilabel>%B</guilabel> and name: <guilabel>%b</guilabel></para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Build</guilabel></term>
-<listitem><para>This option lets you define the build command. It is set to
-<command>make</command> by default.</para></listitem>
+<term><guilabel>Build Command</guilabel></term>
+<listitem><para>The second column in the "non-first rows", contain the shell command to run in
+the working directory. Note the word shell. Almost any shell command will do. The build command can
+contain placeholders. <guilabel>%f</guilabel> for current file, <guilabel>%d</guilabel> for directory
+of current file and <guilabel>%n</guilabel> for the base-name of the current (file name without
+suffix).</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Clean</guilabel></term>
-<listitem><para>The option lets you define the clean command. It is set to
-<command>make clean</command> by default.</para></listitem>
+<term><guilabel>Run Command</guilabel></term>
+<listitem><para>The third column in the "non-first rows", can contain a shell command, for execution
+in an actual terminal in the target-set working directory. The terminal is opened as a tab. The plugin
+will try to reuse the terminal tab, if the same command is executed and the previous application has
+exited.</para></listitem>
</varlistentry>
-<varlistentry>
-<term><guilabel>Config</guilabel></term>
-<listitem><para>This option lets you define the config command. It is set
-to <command>cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr/local ../</command>
-by default.</para></listitem>
-</varlistentry>
</variablelist>
-<para>On the top this plugin has a toolbar with the following buttons :</para>
+<para>On the top of the <guilabel>Target Settings</guilabel> tab, we have a toolbar with a target
+filter and the following buttons:</para>
<simplelist>
<member>
-<guiicon><inlinemediaobject><imageobject><imagedata fileref="dialog-ok-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
+<guiicon><inlinemediaobject><imageobject><imagedata fileref="run-build-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Build the selected target</member>
<member>
+<guiicon><inlinemediaobject><imageobject><imagedata fileref="media-playback-start-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
+Build and run the selected target</member>
+<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="list-add-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Add a new build target</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="document-new-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
-Create a new build target set</member>
+Create a new set of targets</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="edit-copy-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Copy a command or target set</member>
@@ -673,19 +688,14 @@ Delete the current command or target set</member>
<title>Output tab</title>
<para>The <guilabel>Output</guilabel> tab shows the console output generated by
-the last command.</para>
-
-<para>Use the slider at the top to show or hide categories of output:</para>
-
-<para><guilabel>Full Output</guilabel>, <guilabel>Parsed Output</guilabel>,
-<guilabel>Errors and Warnings</guilabel> or <guilabel>Only Errors</guilabel>
+the running (build) command. If a line contains a file location, that line will be clickable.
+If the line in the output also shows an error or warning, the line will have a different color.
</para>
-<para>Each line contains a message and the file name and line number if available.
-Clicking on the error or warning takes you to the appropriate file and places
-the cursor on the corresponding line number.</para>
+<para>If the option <guilabel>Add errors and warnings to Diagnostics</guilabel> is enabled in the
+plugin's settings page in Kate settings, the errors and warnings will also be added to the diagnostics view.
-<para>To navigate to the previous error, press
+To navigate to the previous error in the diagnostics view, press
<keycombo action="simul">&Alt;&Shift;&Left;</keycombo>.
To navigate to the next error, press
<keycombo action="simul">&Alt;&Shift;&Right;</keycombo>.</para>
@@ -699,23 +709,36 @@ To navigate to the next error, press
<variablelist id="build-build">
<varlistentry>
<term><menuchoice id="build-targets">
-<guimenu>Build</guimenu><guisubmenu>Select Target</guisubmenu>
+<guimenu>Build</guimenu><guisubmenu>Select Target...</guisubmenu>
</menuchoice></term>
-<listitem><para>Select from a list of targets configured by the user.</para></listitem>
+<listitem><para>The target selection filter is focused in the Target Settings tab. Typing a name will filter
+out targets that do not match the typed string. It is also possible to use the arrow keys to navigate the
+tree of targets. When the wanted target is selected, pressing <guilabel>Return</guilabel> or
+<guilabel>Enter</guilabel> will execute and run the selected target.</para></listitem>
</varlistentry>
-<varlistentry id="build-default">
+<varlistentry id="build-selected">
<term><menuchoice>
-<guimenu>Build</guimenu><guimenuitem>Build Default Target</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Build Selected Target</guimenuitem>
</menuchoice></term>
-<listitem><para>Builds the target defined as default in the active target set.</para></listitem>
+<listitem><para>Builds the last selected target. If none has been selected, it works as
+<guilabel>Select Target...</guilabel></para></listitem>
</varlistentry>
-<varlistentry id="build-previous">
+<varlistentry id="build-selected-run">
<term><menuchoice>
-<guimenu>Build</guimenu><guimenuitem>Build Previous Target</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Build and Run Selected Target</guimenuitem>
</menuchoice></term>
-<listitem><para>Switch to the previous target configured by the user.</para></listitem>
+<listitem><para>Builds the last selected target and run the run command after the build command has
+finished successfully.</para></listitem>
+</varlistentry>
+
+<varlistentry id="build-currentfile">
+<term><menuchoice>
+<guimenu>Build</guimenu><guimenuitem>Compile Current File</guimenuitem>
+</menuchoice></term>
+<listitem><para>Try to compile the current file by searching for a command in a possible
+compile_commands.json.</para></listitem>
</varlistentry>
<varlistentry id="build-stop">
@@ -725,22 +748,27 @@ To navigate to the next error, press
<listitem><para>Stop building a target.</para></listitem>
</varlistentry>
-<varlistentry id="build-previous-error">
+<varlistentry id="build-previous-run-tab">
+<term><menuchoice>
+<guimenu>Build</guimenu><guimenuitem>Focus Next Tab to the Left</guimenuitem>
+</menuchoice></term>
+<listitem><para>Focus the next build plugin tab to the left. Or open the build plugin tool-view if it is hidden.</para></listitem>
+</varlistentry>
+
+<varlistentry id="build-next-run-tab">
<term><menuchoice>
-<shortcut><keycombo action="simul">&Ctrl;&Alt;&Left;</keycombo></shortcut>
-<guimenu>Build</guimenu><guimenuitem>Previous Error</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Focus Next Tab to the Right</guimenuitem>
</menuchoice></term>
-<listitem><para>Moves the cursor to the location of the previous error in the
-document.</para></listitem>
+<listitem><para>Focus the next build plugin tab to the right. Or open the build plugin tool-view if it is hidden.</para></listitem>
</varlistentry>
-<varlistentry id="build-next-error">
+<varlistentry id="build-load-cmake-targets">
<term><menuchoice>
-<shortcut><keycombo action="simul">&Ctrl;&Alt;&Right;</keycombo></shortcut>
-<guimenu>Build</guimenu><guimenuitem>Next Error</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Load targets from CMake Build Dir</guimenuitem>
</menuchoice></term>
-<listitem><para>Moves the cursor to the location of the next error in the
-document.</para></listitem>
+<listitem><para>Opens the file dialog and let's the user select a <guilabel>CMakeCache.txt</guilabel>.
+When a file is selected, the plugin generates cmake build command targets that can be executed in
+the build directory for the CMake based project.</para></listitem>
</varlistentry>
</variablelist>
diff --git a/doc/kate/run-build-22.png b/doc/kate/run-build-22.png
new file mode 100644
index 0000000000..c9a1dd610e
Binary files /dev/null and b/doc/kate/run-build-22.png differ