hprofile.1

.\"
.\" CopyLeft (c) 2015-6 tokiclover <tokiclover@gmail.com>
.\"
.\" Distributed under the terms of the GNU General Plublic License version 2
.\" as pugblished by the Free Software Fondation, Inc.
.\"
.pc
.TH HPROFILE 1 "2018-07-26" "6.2.0" "Hprofile Script Page"
.SH NAME
hprofile \- soft/hardware profiles management utility
.SH DESCRIPTION
This shell script utility can manage multiple profiles, be it hardware, or sotware related.
A
.I profile
(in hprofile terms) is just a functions file defining
child profiles {start,stop}_<profile> functions and other helpers; And
(configuration) files to be swaped, actualy symlinked, when the appropriate profile
becomes active. See
.B LAYOUTS
and
.B FILES
sub-sections for more info on the layout of a (parrent) profile.
.SH SYNOPSIS
The following conventions apply to
.B SYNOPSIS
and
.B LAYOUTS
sections and is also applicable to the command line arguments.
.TS
tab (@);
l lx.
\fBbold text\fR@T{
type exactly as shown
T}
\fIitalic text\fR@T{
replace with appropriate argument
T}
[\|text\|]@T{
any or all argument within [ ] are optional
T}
.TE

.B hprofile
.RB [\| -d|--debug \|]
.RB [\| -x|--trace \|]
.RB [\| -f|--force \|]
.RB [\| -u|--user= \|\c
.RI \| <user> \|]
.RI \| <type> \|\c
.RB [\| .\fI<profile>\fR \|]

.B hprofile
.RB [\| \-c|--current= \|\c
.RI \| <type> \|]
.RB [\| -l|--list= \|\c
.RI \| <type> \|]
.RB [\| -r|--revert= \|\c
.RI \| <type> \|]
.RB [\| -s|--stop= \|\c
.RI \| <type> \|]
.RB [\| -t|--type \|]

.B hprofile
.RB [\| -h|--help \|]
.RB [\| -v|--version \|]
.SH LAYOUTS
A hprofile
.I <PROFILE>
is a shell functions file and an optional directory hierarchy that may contain
system mirror files.
Almost everything is optional, meaning a profile could have only child profiles
`{start,stop}_<profile>' defined in `<PROFILE>-functions' file.
{start,stop}{,_{post,pre}} functions can be used to do common tasks before and
or after starting and or stopping a child profile.

To sum up, only `\fI<PROFILE>-functions\fR' file is required along with at least
a `start_<profile>' function for each child profile to define a valid profile.
A list of child profiles is defined using `PROFILES' variable, while the default
child profile is defined with \fBPROFILE_DEFAULT\fR variable.

Note that, alternatively, <PROFILE>/functions layout is also supported (see vga
profile) to permit having everything in a single directory.
.TP
.B /etc/hprofile/\fI<PROFILE>(-|/)functions\fR
.TS
tab (@);
l lx.
\fBPROFILE_DEFAULT\fR@T{
Default child profile to use when starting (parent) profile type (optional)
T}
\fBPROFILES\fR@T{
List supported (chid) profiles (required)
T}
\fBstart_test\fR@T{
Dynamic profile probing function to determine which (child) profile to use (optional)
T}
\fBstart_post\fR@T{
Clean up helper executed after starting a child profile (optional)
T}
\fBstart_pre\fR@T{
Set up helper executed before starting a chid profile (optional)
T}
\fBstop_post\fR@T{
Clean up helper executed after stopping a child profile (optional)
T}
\fBstop_pre\fR@T{
Set up helper executed before stopping a child profile (optional)
T}
\fBstart_<profile>\fR@T{
Start helper executed to activate a child profile (optional)
T}
\fBstop_<profile>\fR@T{
Stop helper executed to deactivate a child profile (optional)
T}
.TE
.RE
.TP
.B <PROFILE>/**/*.<profile>

Files hierarchy to swap (or rather symlink) when a child profile become active,
files found in `<PROFILE>/' directory
with the extension `.<profile>' are symlinked to the file system (minus the
`/etc/hprofile/<PROFILE>' head.)
.SH HELPERS
Some helpers are internally available to print formated string output or, eg., to
start another PROFILE using \fIprofile()\fR function (See power profile for a
pratical example which use this to start disk profile in each start_<profile>.)

.TS
tab (@);
l lx.
\fBbegin message\fR@T{
Print begin message
T}
\fBend retval, mssage\fR@T{
Print end message
T}
\fBinfo mssage\fR@T{
Print info message
T}
\fBwarn mssage\fR@T{
Print warn message
T}
\fBerror mssage\fR@T{
Print error message
T}
\fBdie retval mssage\fR@T{
Print error message
T}
\fB${name}\fR@T{
String used to prepend message with the previous helpers
T}
.TE

.SH ENVIRONMENT
.TP
.B CONFDIR=/etc/hprofile
System wide profile directory
.TP
.B PROFILE_DIR=CONFDIR|HOME/.hprofile
Environment variable holding the current profile directory
.TP
.B PROFILE_FILE=PROFILE_DIR/<profile>(-|/)functions
Environment variable holding the current profile file
.TP
.B PROFILE_TYPE
Enviroment variable holding the (parent) profile type
.TP
.B PROFILE_NAME
Enviroment variable holding the (child) profile name
.TP
.B RUNDIR=/var/run
Run-time directory (for <profile>-{current,previous} files)
.TP
.B NULL=/dev/null
Enviroment variable defining null file
.TP
.B PRINT_COLOR=No
Dis/enable output color support
.TP
.B name
Variable holding the header of message output
.TP
.B COLOR_{BLACK,RED,GREEN,YELLOW,BLUE,MAGENTA,CYAN,WHITE,RESET,BOLD,UNDERLINE,ITALIC}
ANSI color escape sequences for black, red, green, yellow, blue, magenta, cyan,
white, reset, bold, underline and italic.
.SH EXAMPLES
Start power profile depending on hardware state
  hprofile power

Probe the actual power profile
  hprofile -c power
.SH FILES
.TP
.BR /etc/{conf,init}.d/hprofile
.B hprofile
init service script along with its configuration file.
.TP
.BR /etc/hprofile/<PROFILES>
.TP
.B <PROFILES> {disk,power,rfkill,vga}

Each PROFILE has a files hierarchy and (child-)profiles.
The following (child-)profile name scheme conventions that apply to
.B PROFILES
sub-section and can be applied to the following (parrent) profiles.
.TS
tab (@);
l lx.
\fBadp\fR@T{
AC power adaptater connected
T}
\fBbat\fR@T{
AC power adaptater disconnected (battery profile)
T}
\fBdyn\fR@T{
Dynamic hprofile (AC power may be connected or not)
T}
\fBquiet\fR@T{
Quiet profile (silence oriented profile)
T}
\fBmed\fR@T{
Medium profile (balence between qerformance & quiet)
T}
.TE
.TP
.B disk-functions

This profile is tailored to manage hard disk drive and thus depends on hdparm.
.TP
.B power-functions

This profile was made to be a superset of other profiles, so it depends on disk
profile. Other profiles can be added (like rfkill profile, for example.)
.TP
.B rfkill-functions

RFKill wireless radio profile (Note: B for Bluetooth, W for Wireless, K for Kill, and
SW for SWitch.)
.TP
.B vga/functions
.RB vga/etc/X11/xorg.conf.d/40-monitor.conf.{fglrx,intel,nouveau,nv,nvidia,radeon}

Graphics Hardware (GPU) profile that can be used to switch between different
hardware and or drivers.
.br
.B WARNING: This profile should be used out of X server.
And do not forget to check the profiles if nVidia/Fglrx profiles are used;
in which case building uVESAfb as kernel module is necessary to be able to
get Linux Console.
.SH AUTHORS
tokiclover <tokiclover@hprofile.project>
.\"
.\" vim:fenc=utf-8:ft=groff:ci:pi:sts=2:sw=2:ts=2:expandtab:
.\"