/*
    gammaray-getting-started.qdoc

    This file is part of the GammaRay documentation.

    Copyright (C) 2016 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com
    Author: Volker Krause <volker.krause@kdab.com>

    Licensees holding valid commercial KDAB GammaRay licenses may use this file in
    accordance with GammaRay Commercial License Agreement provided with the Software.

    Contact info@kdab.com if any conditions of this licensing are not clear to you.

    This work is also licensed under the Creative Commons Attribution-ShareAlike 4.0
    International License. See <http://creativecommons.org/licenses/by-sa/4.0/>.
*/

/*!
    \contentspage {GammaRay User Manual}
    \nextpage {Graphical Launcher}
    \previouspage {Gammaray User Manual}
    \page gammaray-getting-started.html

    \title Getting Started

    \section1 Launching a new application

    \section2 On the command line

    Launching an application with GammaRay on the command line is similar to valgrind: "gammaray <gammaray-args> <app> <app-args>".

    This will launch the application with GammaRay attached to it right from the start. The GammaRay arguments allows you to select a different injection method. Check this list for which one is best for your use case (the default is usually ok on most platforms).

    \section2 With a graphical user interface

    Starting from GammaRay 1.1, launching applications is also available in the graphical user interface. Launch GammaRay without command line arguments (or use the menu shortcut if you have one), select the "Launch" tab. There you can select the executable to launch as well as optional command line arguements to pass to it.

    \section2 On an embedded target

    If you want to run the GammaRay UI on a different machine, which is commonly the case for embedded targets, you can proceed as described in the command line section above, with the extra "--inject-only" argument passed to GammaRay. Then follow the instructions below on how to connect to a already running instance.

    \section1 Attaching to a running application

    \section2 On the command line

    Attaching to a running application on the command line is similar to gdb: "gammaray <gammaray-args> --pid <pid>".

    This will attach GammaRay to the application running with process id "<pid>". Keep in mind that this process has to be a Qt application with matching build settings and Qt version for GammaRay to work. You can also choose different injection methods here, but currently there exists only one that can do runtime attaching on each platform, so this is mainly interesting for GammaRay developers.

    \section2 With a graphical user interface

    Launch GammaRay without command line arguments (or use the menu shortcut if you have one) to bring up the GammaRay UI. It will show you a list of processes GammaRay can attach to, ie. those with the same build settings and Qt version as your GammaRay instance. From GammaRay 1.1 onward you'll find the process list on the "Attach" tab.

    \section2 On an embedded target

    If you want to run the GammaRay UI on a different machine, which is commonly the case for embedded targets, you can proceed as described in the command line section above, with the extra "--inject-only" argument passed to GammaRay. Then follow the instructions below on how to connect to a already running instance.

    \section1 Connect to an already running instance

    \section2 On the command line

    Run "gammaray --connect :", and insert the IP address or host name of the target device, and if needed the port number accordingly. The port number can usually be omitted if there's only a single GammaRay instance active on the target. The port number to use is printed on the command line after injection as described above.

    \section2 With a graphical user interface

    Launch GammaRay without any command line arguments to get to the launcher UI. Select the "Connect" tab. Depending on your network setup active targets will be already listed here and can simply be selected from the list. Manual entry of host name or IP address, and if necessary the port number is also possible.
*/
