diff options
-rw-r--r-- | README.md | 31 | ||||
-rwxr-xr-x | kerl | 213 |
2 files changed, 226 insertions, 18 deletions
@@ -614,6 +614,37 @@ other tools to extract to path information. $ kerl path 19.2.3 /aux/erlangs/19.2.3 +### install-docsh + + kerl install-docsh + +Install `erl` shell documentation access +extension - [docsh](https://github.com/erszcz/docsh). +This extends the shell with new helpers, which enable access to full +function help (via `h/{1,2,3}`), function specs (`s/{1,2,3}`) and type +information (`t/{1,2,3}`). + +If you already have an OTP installation, you will need to remove it and +re-install it **before** you execute `install-docsh`, +since docsh needs some environment variables of its own to be set up +and managed by the activate script. + +Activating a docsh-enabled Erlang installation will try to create +a `$HOME/.erlang` symlink. +If this file exists (i.e. you have created it manually), +please consider removing it - otherwise, docsh won't work. +Deactivating the kerl Erlang installation will remove the symlink. + +Alternatively, if the file exists and you have to keep it you can extend +it with the content of [a docsh-specific `.erlang`][docsh-dot-erlang] - this +task is left as an exercise for the reader - and export +`KERL_DOCSH_DOT_ERLANG=exists` to silence unwanted warnings. +The [manual setup guide][docsh-manual-setup] will probably come in handy +if you decide to take this route. + +[docsh-dot-erlang]: https://github.com/erszcz/docsh/blob/2d9843bce794e726f591bbca49c88aedbb435f8c/templates/dot.erlang +[docsh-manual-setup]: https://github.com/erszcz/docsh/blob/ecf35821610977e36b04c0c256990a5b0dab4870/doc/manual-setup.md + Compiling crypto on Macs ------------------------ Apple stopped shipping OpenSSL in OS X 10.11 (El Capitan) in favor of Apple's @@ -29,6 +29,7 @@ KERL_VERSION="1.7.0" #Grep fix for mac pcre errors GREP_OPTIONS='' +DOCSH_GITHUB_URL="https://github.com/erszcz/docsh.git" ERLANG_DOWNLOAD_URL="http://www.erlang.org/download" KERL_CONFIG_STORAGE_FILENAME=".kerl_config" @@ -173,19 +174,20 @@ usage() echo "usage: $0 <command> [options ...]" printf "\n <command> Command to be executed\n\n" echo "Valid commands are:" - echo " build Build specified release or git repository" - echo " install Install the specified release at the given location" - echo " deploy Deploy the specified installation to the given host and location" - echo " update Update the list of available releases from your source provider" - echo " list List releases, builds and installations" - echo " delete Delete builds and installations" - echo " path Print the path of a given installation" - echo " active Print the path of the active installation" - echo " plt Print Dialyzer PLT path for the active installation" - echo " status Print available builds and installations" - echo " prompt Print a string suitable for insertion in prompt" - echo " cleanup Remove compilation artifacts (use after installation)" - echo " version Print current version (current: $KERL_VERSION)" + echo " build Build specified release or git repository" + echo " install Install the specified release at the given location" + echo " deploy Deploy the specified installation to the given host and location" + echo " update Update the list of available releases from your source provider" + echo " list List releases, builds and installations" + echo " delete Delete builds and installations" + echo " install-docsh Install erl shell documentation access extension - docsh" + echo " path Print the path of a given installation" + echo " active Print the path of the active installation" + echo " plt Print Dialyzer PLT path for the active installation" + echo " status Print available builds and installations" + echo " prompt Print a string suitable for insertion in prompt" + echo " cleanup Remove compilation artifacts (use after installation)" + echo " version Print current version (current: $KERL_VERSION)" exit 1 } @@ -402,7 +404,7 @@ do_git_build() GIT=$(echo -n "$1" | $MD5SUM | cut -d ' ' -f $MD5SUM_FIELD) mkdir -p "$KERL_GIT_DIR" || exit 1 cd "$KERL_GIT_DIR" || exit 1 - echo "Checking Erlang/OTP git repository from $1..." + echo "Checking out Erlang/OTP git repository from $1..." if [ ! -d "$GIT" ]; then git clone -q --mirror "$1" "$GIT" > /dev/null 2>&1 if [ $? -ne 0 ]; then @@ -863,6 +865,14 @@ kerl_deactivate() export PS1 unset _KERL_SAVED_PS1 fi + if [ -n "\$_KERL_DOCSH_DOT_ERLANG" ]; then + rm "\$HOME/.erlang" + unset _KERL_DOCSH_DOT_ERLANG + fi + if [ -n "\$_KERL_DOCSH_USER_DEFAULT" ]; then + unset DOCSH_USER_DEFAULT + unset _KERL_DOCSH_USER_DEFAULT + fi if [ -n "\$BASH" -o -n "\$ZSH_VERSION" ]; then hash -r fi @@ -905,6 +915,21 @@ if [ -n "\$KERL_ENABLE_PROMPT" ]; then PS1="\$PRMPT\$PS1" export PS1 fi +if [ -d "$absdir/lib/docsh" ]; then + export DOCSH_USER_DEFAULT="$absdir/lib/docsh/user_default" + export _KERL_DOCSH_USER_DEFAULT=yes + if [ -f "\$HOME/.erlang" ]; then + if [ ! x"\$KERL_DOCSH_DOT_ERLANG" = x"exists" ]; then + echo "Couldn't symlink correct \$HOME/.erlang - file exists - docsh might not work." + echo "Please make sure \$HOME/.erlang contains code" + echo "from $absdir/lib/docsh/dot.erlang" + echo "and export KERL_DOCSH_DOT_ERLANG=exists to suppress this warning." + fi + else + ln -s "$absdir/lib/docsh/dot.erlang" "\$HOME/.erlang" + export _KERL_DOCSH_DOT_ERLANG=yes + fi +fi if [ -n "\$BASH" -o -n "\$ZSH_VERSION" ]; then hash -r fi @@ -948,6 +973,14 @@ function kerl_deactivate --description "deactivate erlang environment" end | psub ) functions --erase _kerl_saved_prompt end + if set --query _KERL_DOCSH_DOT_ERLANG + rm "\$HOME/.erlang" + set --erase _KERL_DOCSH_DOT_ERLANG + end + if set --query _KERL_DOCSH_USER_DEFAULT + set --erase DOCSH_USER_DEFAULT + set --erase _KERL_DOCSH_USER_DEFAULT + end if test "\$argv[1]" != "nondestructive" functions --erase kerl_deactivate functions --erase _kerl_remove_el @@ -972,13 +1005,28 @@ if set --query KERL_ENABLE_PROMPT _kerl_saved_prompt end end +if test -d "$absdir/lib/docsh" + set -x DOCSH_USER_DEFAULT "$absdir/lib/docsh/user_default" + set -x _KERL_DOCSH_USER_DEFAULT yes + if test -f "\$HOME/.erlang" + if test ! x"\$KERL_DOCSH_DOT_ERLANG" = x"exists" + echo "Couldn't symlink correct \$HOME/.erlang - file exists - docsh might not work." + echo "Please make sure \$HOME/.erlang contains code" + echo "from $absdir/lib/docsh/dot.erlang" + echo "and export KERL_DOCSH_DOT_ERLANG=exists to suppress this warning." + end + else + ln -s "$absdir/lib/docsh/dot.erlang" "\$HOME/.erlang" + set -x _KERL_DOCSH_DOT_ERLANG yes + end +end ACTIVATE_FISH cat <<ACTIVATE_CSH > "$absdir/activate.csh" # This file must be used with "source bin/activate.csh" *from csh*. # You cannot run it directly. -alias kerl_deactivate 'test \$?_KERL_SAVED_PATH != 0 && setenv PATH "\$_KERL_SAVED_PATH" && unset _KERL_SAVED_PATH; rehash; test \$?_KERL_SAVED_MANPATH != 0 && setenv MANPATH "\$_KERL_SAVED_MANPATH" && unset _KERL_SAVED_MANPATH; test \$?_KERL_SAVED_REBAR_PLT_DIR != 0 && setenv REBAR_PLT_DIR "\$_KERL_SAVED_REBAR_PLT_DIR" && unset _KERL_SAVED_REBAR_PLT_DIR; test \$?_KERL_ACTIVE_DIR != 0 && unset _KERL_ACTIVE_DIR; test \$?_KERL_SAVED_PROMP != 0 && set prompt="\$_KERL_SAVED_PROMP" && unset _KERL_SAVED_PROMP; test "\!:*" != "nondestructive" && unalias deactivate' +alias kerl_deactivate 'test \$?_KERL_SAVED_PATH != 0 && setenv PATH "\$_KERL_SAVED_PATH" && unset _KERL_SAVED_PATH; rehash; test \$?_KERL_SAVED_MANPATH != 0 && setenv MANPATH "\$_KERL_SAVED_MANPATH" && unset _KERL_SAVED_MANPATH; test \$?_KERL_SAVED_REBAR_PLT_DIR != 0 && setenv REBAR_PLT_DIR "\$_KERL_SAVED_REBAR_PLT_DIR" && unset _KERL_SAVED_REBAR_PLT_DIR; test \$?_KERL_ACTIVE_DIR != 0 && unset _KERL_ACTIVE_DIR; test \$?_KERL_DOCSH_USER_DEFAULT != 0 && unsetenv DOCSH_USER_DEFAULT && unset _KERL_DOCSH_USER_DEFAULT; test \$?_KERL_DOCSH_DOT_ERLANG != 0 && rm "\$HOME/.erlang" && unset _KERL_DOCSH_DOT_ERLANG; test \$?_KERL_SAVED_PROMPT != 0 && set prompt="\$_KERL_SAVED_PROMPT" && unset _KERL_SAVED_PROMPT; test "\!:*" != "nondestructive" && unalias deactivate' # Unset irrelevant variables. kerl_deactivate nondestructive @@ -1021,6 +1069,22 @@ if ( \$?KERL_ENABLE_PROMPT ) then set prompt = "\$PROMPT\$prompt" endif +if ( -d "$absdir/lib/docsh" ) then + setenv DOCSH_USER_DEFAULT "$absdir/lib/docsh/user_default" + set _KERL_DOCSH_USER_DEFAULT = "yes" + if ( -f "\$HOME/.erlang" ) then + if ( \$?KERL_DOCSH_DOT_ERLANG == 0 ) then + echo "Couldn't symlink correct \$HOME/.erlang - file exists - docsh might not work." + echo "Please make sure \$HOME/.erlang contains code" + echo "from $absdir/lib/docsh/dot.erlang" + echo "and export KERL_DOCSH_DOT_ERLANG=exists to suppress this warning." + endif + else + ln -s "$absdir/lib/docsh/dot.erlang" "\$HOME/.erlang" + set _KERL_DOCSH_DOT_ERLANG = "yes" + endif +endif + rehash ACTIVATE_CSH @@ -1082,6 +1146,99 @@ ACTIVATE_CSH echo "kerl_deactivate" } +install_docsh() { + REPO_URL=$DOCSH_GITHUB_URL + GIT=$(echo -n $REPO_URL | $MD5SUM | cut -d ' ' -f $MD5SUM_FIELD) + BUILDNAME=$1 + DOCSH_DIR="$KERL_BUILD_DIR/$BUILDNAME/docsh" + DOCSH_REF="0.4.0" + ACTIVE_PATH=$2 + + OTP_VERSION=$(get_otp_version $1) + # This has to be updated with docsh updates + DOCSH_SUPPORTED="^1[89]$" + echo $OTP_VERSION | grep "$DOCSH_SUPPORTED" > /dev/null 2>&1 + if [ $? -ne 0 ]; then + echo "Erlang/OTP version $OTP_VERSION not supported by docsh (does not match regex $DOCSH_SUPPORTED)" + exit 1 + fi + + mkdir -p "$KERL_GIT_DIR" || exit 1 + cd "$KERL_GIT_DIR" || exit 1 + echo "Checking out docsh git repository from ${REPO_URL}..." + if [ ! -d "$GIT" ]; then + git clone -q --mirror "$REPO_URL" "$GIT" > /dev/null 2>&1 + if [ $? -ne 0 ]; then + echo "Error mirroring remote git repository" + exit 1 + fi + fi + cd "$GIT" || exit 1 + git remote update --prune > /dev/null 2>&1 + if [ $? -ne 0 ]; then + echo "Error updating remote git repository" + exit 1 + fi + + rm -Rf "$DOCSH_DIR" + mkdir -p "$DOCSH_DIR" || exit 1 + cd "$DOCSH_DIR" || exit 1 + git clone -l "$KERL_GIT_DIR/$GIT" $DOCSH_DIR > /dev/null 2>&1 + if [ $? -ne 0 ]; then + echo "Error cloning local git repository" + exit 1 + fi + cd $DOCSH_DIR || exit 1 + git checkout "$DOCSH_REF" > /dev/null 2>&1 + if [ $? -ne 0 ]; then + git checkout -b "$DOCSH_REF" "$DOCSH_REF" > /dev/null 2>&1 + fi + if [ $? -ne 0 ]; then + echo "Couldn't checkout specified version" + rm -Rf "$DOCSH_DIR" + exit 1 + fi + + ./rebar3 compile + if [ $? -ne 0 ]; then + echo "Couldn't compile docsh" + rm -Rf "$DOCSH_DIR" + exit 1 + fi + + ## Install docsh + if [ -f $ACTIVE_PATH/lib/docsh ]; then + echo "Couldn't install $ACTIVE_PATH/lib/docsh - the directory already exists" + rm -Rf "$DOCSH_DIR" + exit 1 + else + cp -R $DOCSH_DIR/_build/default/lib/docsh $ACTIVE_PATH/lib/ + fi + ## Prepare dot.erlang for linking as $HOME/.erlang + if [ -f $ACTIVE_PATH/lib/docsh/dot.erlang ]; then + echo "Couldn't install $ACTIVE_PATH/lib/docsh/dot.erlang - the file already exists" + rm -Rf "$DOCSH_DIR" + exit 1 + else + cat $DOCSH_DIR/templates/dot.erlang > $ACTIVE_PATH/lib/docsh/dot.erlang + fi + ## Warn if $HOME/.erlang exists + if [ -f $HOME/.erlang ]; then + echo "$HOME/.erlang exists - kerl won't be able to symlink a docsh-compatible version." + echo "Please make sure your $HOME/.erlang contains code" + echo "from $ACTIVE_PATH/lib/docsh/dot.erlang" + echo "and export KERL_DOCSH_DOT_ERLANG=exists to suppress further warnings" + fi + ## Install docsh user_default + if [ -f $ACTIVE_PATH/lib/docsh/user_default.beam ]; then + echo "Couldn't install $ACTIVE_PATH/lib/docsh/user_default.beam - the file already exists" + rm -Rf "$DOCSH_DIR" + exit 1 + else + erlc -I $DOCSH_DIR/include -o $ACTIVE_PATH/lib/docsh/ $DOCSH_DIR/templates/user_default.erl + fi +} + download_manpages() { FILENAME=otp_doc_man_$1.tar.gz @@ -1133,7 +1290,7 @@ do_plt() return 1 fi else - echo "No Erlang/OTP kerl installation is currently active" + echo "No Erlang/OTP installation is currently active" return 2 fi } @@ -1438,7 +1595,7 @@ do_active() echo "$ACTIVE_PATH" return 0 else - echo "No Erlang/OTP kerl installation is currently active" + echo "No Erlang/OTP installation is currently active" return 1 fi } @@ -1714,6 +1871,26 @@ case "$1" in fi fi ;; + install-docsh) + ACTIVE_PATH="$(get_active_path)" + if [ -n "$ACTIVE_PATH" ]; then + ACTIVE_NAME="$(get_name_from_install_path "$ACTIVE_PATH")" + if [ -z "$ACTIVE_NAME" ]; then + ## TODO: Are git builds installed the usual way + ## or do we need this clause to provide a fallback? + #BUILDNAME="$(basename "$ACTIVE_PATH")" + echo "$ACTIVE_PATH is not a kerl installation" + exit 1 + else + BUILDNAME="$ACTIVE_NAME" + fi + install_docsh "$BUILDNAME" "$ACTIVE_PATH" + echo "Please kerl_deactivate and activate again to enable docsh" + else + echo "No Erlang/OTP installation is currently active - can't install docsh" + exit 1 + fi + ;; deploy) if [ $# -lt 2 ]; then echo "usage: $0 $1 <[user@]host> [directory] [remote_directory]" @@ -1861,7 +2038,7 @@ case "$1" in do_plt "$ACTIVE_PATH" print_buildopts "$ACTIVE_PATH" else - echo "No Erlang/OTP installation is currently active." + echo "No Erlang/OTP installation is currently active" exit 1 fi fi |