Skip to content

Latest commit

 

History

History
334 lines (311 loc) · 20.6 KB

README.org

File metadata and controls

334 lines (311 loc) · 20.6 KB
Raw

Introductory note

DO NOT LAUNCH the install scripts! They may get rid of your current configuration.

Files hierarchy

bin

some useful scripts

bin_win32

some useful scripts, dedicated to some deficient computers using win32

config

The configuration of the packages I use, respecting the xdg standard. This means that the environment variable XDG_CONFIG_HOME may point to this directory and the application following the xdg standard should retrieve their configuration there.

etc

Some of my global configuration. They are not automatically copied during the install phase because it does not require admin privileges.

init_bin

The entry point of the environment variables handling mechanism.

install*

Scripts to install my configuration on a computer, see Configuration installation for more info.

lib

Some useful functions that I might want in some languages. PYTHONPATH should point to this directory to have access to the libraries and in shell, one can use them with. 
source "${KONIX_LIB_DIR}/lib_bash.sh"

This assumes the environment variable KONIX_LIB_DIR points to this directory.

patches and .pc

Patches to some projects I casually contribute to, quilt powered.

prog

Some snippets of code that might prove useful one day, I admit I never look at them…

share

The content of the share directory as specified by xdg. XDG_DATA_HOME could point to this folder.

tuning

Some useful files for tuning my desktop, like Gnome Delta icons theme.

Configuration installation

The scripts install_* are made to install my configuration files in the home of the current user. They are not designed to keep the previously installed one then be warned that when launched, they will erase your ~/.emacs, ~./.bashrc… before installing mine. This is certainly not what you want.

They are designed to leave all the configuration files into the cloned folder so that any modification made to one of those files may be easily commited. If do not use symlinks to do so because the configuration should be as easy to deploy on any platform. Is it then restricted by the windows lack of symbolic linking.

In order to reach the configuration files, correct environment variables are set up and minimal configuration files are written into the home directory. The scripts in init_bin are used to do so.

How does it work?

For a component to have access to its configuration, one need several things:
  • an entry point : something into ~/.someconfigurationfile.rc
  • a way to get to the true configuration : some environment variables
  • a way to extract the path to the true configuration : the init_bin folder

The installation phase does the following:

  • Create the ~/.env.conf file. Briefly, this file stores the needed information to reach the Devel directory in order to get access to the configuration files. Take a look at the environment variable mechanism for more info about the content of this file. What should be kept in mind is that it indicates that the environment variable KONIX_DEVEL_DIR should contain the path to the Devel directory.
  • Copy the init_bin folder into the HOME directory. This folder stores the needed scripts to extract the environment variables from the ~/.env.conf file and insert them into the environment of the running process. It is composed of a simple python script parsing the file and some wrapper in each language using that information to initialise the environment variables.
  • Launches the install_* scripts that write some minimal code into the canonical configuration file location that:
    • gets the needed information in .env.conf file using the helpers in init_bin
    • load the associated configuration file into the KONIX_DEVEL_DIR folder

What happens during the initialisation phase depends on the running component. Let’s see the example with bash:

  • bash loads the default ~/.bashrc file.
  • in this file, the ~/init_bin/konix_init_lib.sh library is sourced, giving access to the import_env shell function.
  • import_env is called, importing (among others) the KONIX_DEVEL_DIR environment variable
  • the $KONIX_DEVEL_DIR/config/bashrc file is loaded

During the initialisation phase, the component must also set the KONIX_PLATFORM environment variable before it loads the other environment variables. Take a look at environment variables handling for more info about the why of this setting. Briefly, the variable should by the value of what os.sys.platform would return on such platform (linux2, win32, cygwin…).

This assumes that the component’s configuration file is able to include another file or to get the needed information from that file. That is not always the case. Special handling has been done when it was not possible. Take a look for instance at the git installation script.

The content of the default configuration files is generated and should be as small as possible since they are only meant to reach the true configuration files.

Now, lets see in detail how each component is installed.

install_bin.py

Does nothing for the time being, but it could!

install_emacs.py

It writes the file ~/.emacs_var that does:
  • load the ~/init_bin/konix_import_env.el file. This file make sure to provide the needed function to import the environment variables
  • call the function import the environment
  • set some emacs variables useful when configuration emacs:
    • perso-dir: this is where lives my custom emacs configuration, things specific to the computer running emacs and that should not be put in the public repo
    • config-dir: where I put my config files
    • elfiles, where the emacs third library files are located
    • emacs-config-dir, where the emacs configuration files are located
    • devel_dir, the content of the KONIX_DEVEL_DIR environment variable
    • custom-file, the path to a custom emacs configuration file, loaded at the end of the configuration, it is initialised with the content of the KONIX_EMACS_CUSTOM_FILE environment variable

It then writes the ~/.emacs file (the entry point for emacs) that does:

  • loads the ~/.emacs_var
  • loads the emacs.el file in the KONIX_CONFIG_DIR folder
  • loads the custom file if it exists

install_shell.py

As described before, the shell installation script inserts a default template into the ~/.bashrc, ~/.shrc and ~/.zshrc files. Each one is composed of:
  • a line testing whether the shell is launched interactively. In this case, the rest of the configuration is loaded. In the other case, nothing is loaded. This prevent some custom behaviour to be triggered while the calling script might assume the default behaviour to happen
  • a line testing whether the computer is doing much work. If so, the remaining of the configuration is not loaded. This may be useful in case you try to have access to your computer while it is performing too much and even loading configuration file is taking too long. With that trick, you still get access to the machine.
  • load the ~/.shrc_var script. This script performs the code to import the environment variables
  • load the associated configuration file inside the ${KONIX_CONFIG_DIR} directory. It is shrc for sh, bashrc for bash and zshrc for zsh.
  • load the content of the ${KONIX_SH_CUSTOM_FILE}, it might be useful when wanting to customise the loading of the shell

install_gdbinit.py

It writes the ~/.gdbinit file that:
  • sources the gdbinit file in KONIX_CONFIG_DIR
  • sources the stl-views.gdb file in KONIX_CONFIG_DIR, this file may be useful to debug stl objects in debugging sessions. It has been made obsolete in gdb 7 by the possibility to add python printers but that is another story

install_git.py

Because git does not provide any way to source another file, this file is directly copied in the home. This means that the KONIX_CONFIG_DIR/gitconfig file should be changed by hand and then install_git.py re launched each time a change is to be done in the configuration. This is really a pain, and I hope I will find a solution to make it easier in the future. Luckily, I barely change this file. The script copies the KONIX_CONFIG_DIR/gitconfig file in ~/.gitconfig, making sure to conserve the previous values of user name and email. It also adds the konix_sendmail.sh script as sendemail.smtpserver default value because it use it.

This install script should be re done in the future.

install_lib.py

This script does not install anything, it should be imported by all other script in order to get access to useful information like the environment values before installing anything. It also provides some helpers like a function that replaces a file only if the user confirmed he did not mind.

install.py

This is the main installation script, it calls all other install scripts and also:
  • install the ~/.env_[PLATFORM].conf file with the default content of the environment variables. This is the file used by the wrappers when wanting to reach the configuration folder
  • install the ~/init_bin folder with the wrappers in it.
  • calls all the installation script for each component
  • install some default files into the HOME directory. Most of them are historically present and should either be installed via dedicated install_ scripts or not be installed at all, but I did not spend time to tackle them yet.
    • Makefile: I like being able to launch make from HOME and having my most often used project compiled
    • .gitk: Some config about gitk, should be inserted into the install_git script
    • .inputrc
    • .B.blend
    • .screenrc
    • .vimrc
    • .terminator
  • Only on linux platform,
    • install some configuration file those may be kept that way because on linux, I am almost certain I may use symlinks and the limitation of windows is not relevant then
      • .Xdefaults
      • .xinitrc
      • .xsession
      • .gtkrc-2.0
    • install my favorite (Delta) gnome icon themes
    • make sure to add via gconf the configuration of some applications
    • make sure the files inside the binary folder are executable

install_quilt.py

makes sure the folders ~/patches and ~/.pc are symlinks to the ones in devel. There are useful to store random patches about project I may not contribute to directly. For instance, I keep some patch made in emacs that wait to be send upstream. I only have to quilt pop and quilt push to get them back after a pulling of upstream sources and keeping them centralised facilitates synchronisation between computers.

install_seeks.sh

It is not an install script but some reminder about how to compile it

install_vim.py

copies KONIX_CONFIG_DIR/vimrc into the ~/.vimrc file. Now that I know better how vim works and I know the source command exists, I may change this behaviour to ake it more like the one of emacs or shell.

Environment variables handling

Default ones

Those are the default environment variable provided for all the components.
  • KONIX_LIB_DIR
  • KONIX_CONFIG_DIR
  • KONIX_PWD: from where the call to install was done
  • PATH_SEPARATOR: “;” on windows, “:” elsewhere
  • KONIX_BIN_DIR
  • KONIX_DEVEL_DIR
  • KONIX_PLATFORM
  • KONIX_PERSO_DIR: the path to a personal directory where personal stuff should be located. I dislike putting things into ~/ because it become really quickly messy, it default to a folder called perso sibling to the devel folder
  • PYTHON_PATH : the path to the python executable that is to be called to get the environment values. Not used anymore, use PYTHON_BIN instead
  • KONIX_SH_CUSTOM_FILE : a file with the customisation of shell
  • HOME
  • KONIX_SHARE_DIR
  • KONIX_TUNING_DIR
  • KONIX_EMACS_CUSTOM_FILE
  • KONIX_SRC_DIR : path to some sources, not used anymore
  • PYTHON_BIN : the path to the python executable that is to be called to get the environment values

How it works

The core of the environment manager is the python script konix_get_env.py. it reads the content of the env.conf files and prints on stdout the list of environment variables with the format.

NAME=’VALUE’

Its constraints are:

  • it should work on any platform, this caused the python language choice
  • The installation for one platform should not impact the installation for another. This means that if your HOME folder in shared between cygwin and mac for instance, installing the environments for one should not impact on the installation for another. Besides, running on each platform should work correctly and load the default values as well as those specific for each platform.

The script updates the values of the environment variables at the time it is called. For instance, if the variable FOO has the value BAR and if the env.conf file indicates to add :JO to FOO, then the script output will contain

FOO=’BAR:JO’

It is the responsibility of each wrapper to call it and parse the result.

The content of the env.conf files

The env.conf files, written in ini style, are composed of three sections:
  • [Replace]: the value of the environment variables replace the existing value, FOO=’:JO:’
  • [Prefix]: the value of the variable is put before the existing value, FOO=’:JOBAR’
  • [Suffix]: the value of the variable is put after the existing value, FOO=’BAR:JO’

Note: prefer using KONIX_PATH_SEPARATOR instead of : to have something platform independent.

Each section may be repeated as many times as wanted, they may be written in any order and they are interpreted in order. For instance, the content

[Prefix]
FOO=BA
[Suffix]
FOO=FU

Will result in FOO getting the value BABARFU.

The env.conf files organisation

The script reads the following files in order
  • possibly a backup env file, see the avoiding loops section for more information
  • KONIX_CONFIG_DIR/env.conf
  • ~/env.conf
  • KONIX_CONFIG_DIR/env_[PLATFORM].conf
  • ~/env_[PLATFORM].conf

The content of the environment variables is updated between each call, meaning that when interpreting the second env.conf file, the content of the variables once passing the first file is taken into account. For instance, if in KONIX_CONFIG_DIR/env.conf, there is

[Prefix]
FOO=BAR

and in ~/env.conf

[Suffix]
FOO=FU

The result will be FOO=BARBAFU.

Avoiding loops

When recursively calling components, for instance if bash loads emacs that loads bash that loads… The associated wrappers may be called several times: once for each call. This may cause environment variables to grow a lot. With the example of FOO given earlier and bash calling emacs calling bash, you get:
  • in bash: FOO BARBAFU
  • in emacs: FOO BARBARBAFUFU
  • in the second bash: FOO BARBARBARBAFUFUFU

To avoid this (unwanted behavior), the content of the environment before interpreting the env.conf files the first time the konix_get_env.py script is called is recorder in HOME/.env_backup/env_RANDOM.conf and the new environment variable KONIX_ENV_BACKUP_FILE is set to the path to that file. When the script is called, it checks whether this variable exists and the given file exist also. If so, the values of this file is inserted before the first env.conf file in the list. This causes all the modified environment variable changed during the parsing of the env.conf files to be set to a default value instead of the defaut environment value.

That means that if you change an environment variable in one of the layer without going through the environment manager process, its value would be forgotten when spawning a child. For instance, if in bash you do: Export FOO YOUPI And then you call emacs, the emacs process will have FOO BARBAFU instead of BARYOUPIFU. There is not any work to adjust this behaviour yet.

The need for PYTHON_BIN

Imagine you are on window, with python and cygwin installed. You then run the cygwin bash and then launch the install script. By default, calling python will call the one of windows and then all the paths are written c:/… Now imagine you just installed cygwin python. Then when running another bash. The new call to python will find the one of cygwin expecting paths like cygwin/c… then the whole installed files won’t be correctly read.

More generally, if you install another version of python on your system (in addition to the one used to install),there might be an conflict between this new version and the content of the written env files.

The wrappers should then make sure it is the python whose path is in PYTHON_BIN that should be called. This is the hacky thing of the system: the wrappers need to know the value of the PYTHON_BIN that should be given by the environment manager script in order to launch the environment manager. I don’t know any cleaner way to do this for the time being.

The wrappers should also know the current platform to know what .env[PLATFORM].conf file to parse. Indeed, imagine your HOME folder is shared between several platforms, then the default environment variables won,t be the same. Guess for instance that KONIX_PATH_SEPARATOR would be : on unix and ; on windows. The wrapper should use some heuristic to know what to put into the KONIX_PLATFORM environment variable so that the konix_get_env.py script will know what to launch. Keep in mind that the value is initialised during the installation phase with the sys.platform value.

New platform

If you want to add support for a new platform, just copy the KONIX_CONFIG_DIR/env_[PLATFORM].conf and ~/env_[PLATFORM].conf file generated during a previous installation and give the platform the name you want. Then make sure the wrappers will set the KONIX_PLATFORM variable to the good value

Magic stuff

  • Captured [2012-12-17 lun. 19:25]