Doc: generic Linux device target

Change-Id: I25fef3d823915c1df424da1a6ec7b683d7d38d66
Reviewed-on: http://codereview.qt.nokia.com/1323

Reviewed-by: Christian Kandeler <christian.kandeler@nokia.com>

doc/config/qtcreator-project.qdocconf

@@ -13,7 +13,7 @@ include(macros.qdocconf)
 include(qt-cpp-ignore.qdocconf)
 include(qt-defines.qdocconf)
 
-sources.fileextensions  = "qtcreator.qdoc maemodev.qdoc symbiandev.qdoc addressbook-sdk.qdoc qtcreator-faq.qdoc"
+sources.fileextensions  = "qtcreator.qdoc maemodev.qdoc symbiandev.qdoc addressbook-sdk.qdoc qtcreator-faq.qdoc linuxdev.qdoc"
 
 
 qhp.projects            = QtCreator

doc/doc.pri

@@ -83,5 +83,5 @@ OTHER_FILES = $$HELP_DEP_FILES $$DEV_HELP_DEP_FILES
 fixnavi.commands = \
     cd $$targetPath($$PWD) && \
     perl fixnavi.pl -Dqcmanual -Dqtquick \
-        qtcreator.qdoc maemodev.qdoc symbiandev.qdoc qtcreator-faq.qdoc
+        qtcreator.qdoc maemodev.qdoc symbiandev.qdoc qtcreator-faq.qdoc linuxdev.qdoc
 QMAKE_EXTRA_TARGETS += fixnavi

doc/linuxdev.qdoc

+/****************************************************************************
+**
+** This file is part of Qt Creator
+**
+** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
+**
+** Contact: Nokia Corporation (info@qt.nokia.com)
+**
+**
+** GNU Free Documentation License
+**
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at info@qt.nokia.com.
+**
+****************************************************************************/
+
+    /*!
+
+    \contentspage index.html
+    \previouspage creator-developing-maemo.html
+    \page creator-developing-generic-linux.html
+    \nextpage creator-developing-symbian.html
+
+    \title Connecting Generic Linux Devices
+
+    You can connect generic Linux devices to the development PC to build, run,
+    debug, and analyze applications on them from Qt Creator.
+
+    If you have the tool chain for building applications for generic Linux
+    devices (with no MADDE support) installed on the development PC, you can add
+    it to Qt Creator.
+
+    To be able to run and debug applications on generic Linux devices, you must
+    create device configurations and select them in the Qt Creator run
+    settings.
+
+    You use a wizard to create the connections. You can edit the settings later
+    in \gui {Tools > Options... > Linux Devices > Device Configurations}.
+
+    \image qtcreator-linux-device-configurations.png "Device Configurations dialog"
+
+    You can protect the connections between Qt Creator and a device by using
+    either a password or an SSH key. If you do not have an SSH key, you can
+    create it in Qt Creator. For more information, see \l {Generating SSH Keys}.
+
+    To configure connections between Qt Creator and generic Linux devices:
+
+    \list 1
+
+        \o  Make sure that your device can be reached via an IP address.
+
+        \o  Select \gui {Tools > Options... > Qt4 > Add} to add the Qt version
+            for the generic Linux.
+
+        \o  Select \gui {Tools > Options... > Tool Chains > Add} to add the tool
+            chain for building the applications.
+
+        \o  To deploy applications and run them remotely on devices, specify
+            parameters for accessing the devices:
+
+            \list 1
+
+                \o  Select \gui {Tools > Options... > Linux Devices > Device
+                    Configurations > Add > Generic Linux Device}.
+
+                    \image qtcreator-screenshot-devconf-linux.png "Connection Data wizard"
+
+                \o  In the \gui {The name to identify this configuration} field,
+                    enter a name for the connection.
+
+                \o  In the \gui {The device's host name or IP address} field,
+                    enter the host name or IP address of the device.
+
+                \o  In the \gui {The user name to log into the device} field,
+                    enter the user name to log into the device and run the
+                    application as.
+
+                \o  In the \gui {The authentication type} field, select whether
+                    to use \gui Password or \gui Key authentication, and enter
+                    the user's password or the file that contains the user's
+                    private key.
+
+                \o Click \gui {Next} to create the connection.
+
+            \endlist
+
+        \o  To specify build settings:
+
+        \list 1
+
+            \o  Open a project for an application you want to develop for the
+                device.
+
+            \o  Select \gui {Projects > Desktop > Build}.
+
+            \o  Select the Qt version and tool chain for the generic Linux
+                device.
+
+        \endlist
+
+        \o To specify run settings:
+
+        \list 1
+
+            \o  Select \gui {Run > Add > Build Tarball and Deploy to Linux Host}
+                to add a new deploy configuration.
+
+                \image qtcreator-run-settings-linux-devices.png "Run settings for generic Linux devices"
+
+            \o  In the \gui {Device configuration} field, select the device
+                connection.
+
+        \endlist
+
+        When you run the project, Qt Creator creates an installation package in
+        the build directory. The name of the directory is displayed in the
+        \gui {Create tarball} step.
+
+        The \gui {Deploy tarball via SFTP upload using device} step specifies
+        that Qt Creator uploads the tarball to the device and extracts it.
+                You can add custom deploy steps and remove the default step if
+                it is incompatible with your steps.
+                To only create a tarball and not copy the files to the device,
+                remove all deploy steps.
+
+    \endlist
+
+*/
+

doc/maemodev.qdoc

@@ -279,7 +279,7 @@
     only need to configure a connection to the device.
 
     You use a wizard to create the connections. You can edit the settings later
-    in \gui {Tools > Options... > Maemo > Maemo Device Configurations}.
+    in \gui {Tools > Options... > Linux Devices > Device Configurations}.
 
     \image qtcreator-maemo-device-configurations.png "Maemo Device Configurations dialog"
 
@@ -327,8 +327,8 @@
             \note If you experience connection problems due to a USB port issue,
             switch to a different port or use WLAN to connect to the device.
 
-            \o Select \gui Tools > \gui Options... > \gui Maemo >
-            \gui{Maemo Device Configurations > Add}, and add a new configuration for a
+            \o Select \gui {Tools > Options... > Linux Devices > Device
+            Configurations > Add}, and add a new configuration for a
             hardware device.
 
             \image qtcreator-screenshot-devconf.png
@@ -363,8 +363,9 @@
 
             \list a
 
-                \o In Qt Creator, select \gui {Tools > Options... > Maemo >
-                Maemo Device Configurations > Add} to add a new configuration.
+                \o In Qt Creator, select \gui {Tools > Options... > Linux
+                Devices > Device Configurations > Add} to add a new
+                configuration.
 
                 \image qtcreator-maemo-emulator-connection.png
 
@@ -431,8 +432,8 @@
         \o To specify the password, enter the following command:
         \c{/usr/lib/mad-developer/devrootsh passwd user}
 
-        \o In Qt Creator, Select \gui Tools > \gui Options... > \gui Maemo >
-        \gui{Maemo Device Configurations}.
+        \o In Qt Creator, select \gui {Tools > Options... Linux Devices >
+         Device Configurations}.
 
         \o Specify the username \c user and the password in the device configuration.
 
@@ -447,7 +448,8 @@
 
          \list 1
 
-             \o Select \gui {Tools > Options... > Maemo > Maemo Device Configurations
+             \o Select \gui {Tools > Options... > Linux Devices > Device
+             Configurations
              > Generate SSH Key...}.
 
              \o Click \gui {Generate SSH Key}.
@@ -468,7 +470,7 @@
 
     You can view processes running on the Maemo or MeeGo Harmattan device and
     kill them.
-    Select \gui {Tools > Options... > Maemo > Maemo Device Configurations >
+    Select \gui {Tools > Options... > Linux Devices > Device Configurations >
     Remote Processes...}.
 
     You can filter the processes by name in the \gui {List of Remote Processes}

doc/qtcreator.qdoc

@@ -66,6 +66,7 @@
                 \o \l{Opening a Project}
                 \o \l{Adding Libraries to Projects}
                 \o \l{Connecting Maemo and MeeGo Harmattan Devices}
+                \o \l{Connecting Generic Linux Devices}
                 \o \l{Connecting Symbian Devices}
                 \o \l{Managing Sessions}
             \endlist
@@ -556,6 +557,8 @@
 
         \o MeeGo Harmattan
 
+        \o Generic remote Linux
+
         \o Symbian
 
     \endlist
@@ -565,13 +568,14 @@
 
     \table
         \header
-            \o {1,5} Operating system
-            \o {5,1} Platform
+            \o {1,6} Operating system
+            \o {6,1} Platform
         \header
             \o Desktop
             \o Qt Simulator
             \o Maemo 5
             \o MeeGo Harmattan
+            \o Generic Remote Linux
             \o Symbian
 
         \row
@@ -581,12 +585,14 @@
             \o Yes
             \o Yes
             \o Yes
+            \o Yes
         \row
             \o Linux
             \o Yes
             \o Yes
             \o Yes
             \o Yes
+            \o Yes
             \o Yes (by using Remote Compiler for building)
         \row
             \o Mac OS X
@@ -594,6 +600,7 @@
             \o Yes
             \o Yes
             \o Yes
+            \o Yes
             \o Yes (by using Remote Compiler for building)
     \endtable
 */
@@ -3197,6 +3204,7 @@
         \o \l{Opening a Project}
         \o \l{Adding Libraries to Projects}
         \o \l{Connecting Maemo and MeeGo Harmattan Devices}
+        \o \l{Connecting Generic Linux Devices}
         \o \l{Connecting Symbian Devices}
         \o \l{Managing Sessions}
     \endlist
@@ -4491,6 +4499,42 @@
 
         Debugging also works transparently.
 
+    \section1 Running on Generic Linux Devices
+
+    \list 1
+
+        \o  Build and run the application for \l{Running on Qt Simulator}
+            {Qt Simulator}.
+
+        \o  Build and run the application for a device:
+
+        \list 1
+
+        \o  Specify a connection to the device. For more information, see
+            \l{Connecting Generic Linux Devices}.
+
+        \o  Click the \gui Run button.
+
+        \endlist
+
+    \endlist
+
+    Qt Creator uses the compiler specified in the project build settings
+    (tool chain) to build the application.
+
+    Qt Creator generates an installation package, installs it on the
+    device, and executes the selected application. The application views are
+    displayed on the device. Command-line output is visible in the Qt
+    Creator \gui {Application Output} view.
+
+    Choose \gui {Projects > Desktop > Run} to view the settings for deploying
+    the application on the connected device and creating the installation
+    package. For more information, see
+    \l{Specifying Run Settings for Generic Linux Devices}.
+
+    Debugging works transparently if GDB server is installed on the device and
+    it is compatible with the GDB on the host.
+
     \section1 Running on Symbian
 
     \list 1
@@ -4915,6 +4959,24 @@
     information, see
     \l{Deploying Applications to Maemo or MeeGo Harmattan Devices}.
 
+    \section2 Specifying Run Settings for Generic Linux Devices
+
+    To run an application on a generic Linux device (without MADDE support),
+    create and select a device configuration in the Desktop run settings for
+    your project. You can also pass command line arguments to your application.
+
+    \image qtcreator-run-settings-linux-devices.png "Run settings for Generic Linux devices"
+
+    In addition, you must create a connection from the development PC to the
+    device.  Click \gui {Manage device configurations} to create connections.
+    For more information, see \l {Connecting Generic Linux Devices}.
+
+    When you run the application on the \gui Desktop target, Qt Creator
+    generates an installation package in the build directory. The name of the
+    directory is displayed in the \gui {Create tarball} step. Qt Creator copies
+    the tarball to devices by using the SSH file transfer protocol (SFTP) and
+    extracts it.
+
     \section1 Specifying a Custom Executable to Run
 
     If you use CMake or the generic project type in Qt Creator, or want
@@ -7816,7 +7878,7 @@
     The on-device mode is a special mode available for run configurations
     targeting mobile devices. It debugs processes running on mobile
     devices using on-device debugging agents, such as CODA on Symbian and
-    gdbserver on Maemo and MeeGo Harmattan.
+    gdbserver on Linux-based devices.
 
     To launch the debugger in the on-device mode, open the project, select a
     run configuration that targets a mobile device, and click the
@@ -10367,7 +10429,8 @@
     If the emulator crashes, you are asked whether you want to try software
     rendering, instead.
 
-    To specify the OpenGL mode, select \gui {Tools > Options... > Maemo > Qemu
+    To specify the OpenGL mode, select \gui {Tools > Options... > Linux Devices
+    > Maemo Qemu
     Settings}.
 
     \section1 Emulating Device Keys

doc/symbiandev.qdoc

@@ -22,7 +22,7 @@
 /*!
     \contentspage index.html
     \if defined(qcmanual)
-    \previouspage creator-developing-maemo.html
+    \previouspage creator-developing-generic-linux.html
     \else
     \previouspage sdk-gs.html
     \endif