[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    [kauth] /: Improve KAuth README.md
From:       Alex Merry <kde () randomguy3 ! me ! uk>
Date:       2014-02-20 12:07:00
Message-ID: E1WGSP6-0006Ja-KA () scm ! kde ! org
[Download RAW message or body]

Git commit 09df54e986e41560b16274380345e282e9e611a7 by Alex Merry.
Committed on 13/01/2014 at 12:23.
Pushed by alexmerry into branch 'master'.

Improve KAuth README.md

REVIEW: 114997

M  +31   -1    README.md

http://commits.kde.org/kauth/09df54e986e41560b16274380345e282e9e611a7

diff --git a/README.md b/README.md
index a8a011a..0cc38fd 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,37 @@ Execute actions as privileged user
 
 ## Introduction
 
-KAuth is a framework to let applications perform actions as a privileged user.
+KAuth provides a convenient, system-integrated way to offload actions that need
+to be performed as a privileged user (root, for example) to small (hopefully
+secure) helper utilities.
+
+## Usage
+
+If you are using CMake, you need to have
+
+    find_package(KF5Auth NO_MODULE)
+
+(or find KF5 with the Auth component) in your CMakeLists.txt file, and you need
+to link to KF5::Auth.
+
+Executing privileged actions typically involves having a minimal helper utility
+that does the actual work, and calling that utility with escalated privileges if
+the user has permission to do so (often requiring the user to enter appropriate
+credentials, like entering a password).
+
+Therefore, use of the KAuth library is in two parts.  In the main part of your
+code, you use KAuth::Action (and specifically KAuth::Action::execute()) when you
+need to do something privileged, like write to a file normally only writable by
+root.
+
+The code that actually performs that action, such as writing to a file, needs to
+be placed in the slot of a helper QObject class, which should use the methods of
+KAuth::HelperSupport and be compiled into an executable.  You will also want to
+use the `kauth_install_helper_files` and `kauth_install_actions` macros in your
+CMakeLists.txt.
+
+See <http://techbase.kde.org/Development/Tutorials/KAuth/KAuth_Basics> for a
+detailed tutorial on how to use KAuth.
 
 ## Links
 
[prev in list] [next in list] [prev in thread] [next in thread]