Add "make help" option

Based on kubernetes controller Makefile help.

Reviewed-by: Richard Levitte <[email protected]>
Reviewed-by: Paul Dale <[email protected]>
(Merged from openssl#20407)

Author: tmshort

.github/workflows/ci.yml

@@ -51,6 +51,8 @@ jobs:
       run: make -s build_generated
     - name: make doc-nits
       run: make doc-nits
+    - name: make help
+      run: make help
     - name: make md-nits
       run: |
           sudo gem install mdl

Configurations/unix-Makefile.tmpl

@@ -20,8 +20,9 @@
      # to. You're welcome.
      sub dependmagic {
          my $target = shift;
+         my $help = shift;
 
-         return "$target: build_generated\n\t\$(MAKE) depend && \$(MAKE) _$target\n_$target";
+         return "$target: build_generated ## $help\n\t\$(MAKE) depend && \$(MAKE) _$target\n_$target";
      }
 
      our $COLUMNS = $ENV{COLUMNS};
@@ -504,15 +505,20 @@ LANG=C
 
 # The main targets ###################################################
 
-{- dependmagic('build_sw'); -}: build_libs_nodep build_modules_nodep build_programs_nodep link-utils
-{- dependmagic('build_libs'); -}: build_libs_nodep
-{- dependmagic('build_modules'); -}: build_modules_nodep
-{- dependmagic('build_programs'); -}: build_programs_nodep
+##@ Software
 
+{- dependmagic('build_sw', 'Build all the software (default target)'); -}: build_libs_nodep build_modules_nodep build_programs_nodep link-utils
+{- dependmagic('build_libs', 'Build the libraries libssl and libcrypto'); -}: build_libs_nodep
+{- dependmagic('build_modules', 'Build the modules (i.e. providers and engines)'); -}: build_modules_nodep
+{- dependmagic('build_programs', 'Build the openssl executables and scripts'); -}: build_programs_nodep
+
+all: build_sw build_docs ## Build software and documentation
+
+##@ Documentation
 build_generated_pods: $(GENERATED_PODS)
-build_docs: build_man_docs build_html_docs
-build_man_docs: $(MANDOCS1) $(MANDOCS3) $(MANDOCS5) $(MANDOCS7)
-build_html_docs: $(HTMLDOCS1) $(HTMLDOCS3) $(HTMLDOCS5) $(HTMLDOCS7)
+build_docs: build_man_docs build_html_docs ## Create documentation
+build_man_docs: $(MANDOCS1) $(MANDOCS3) $(MANDOCS5) $(MANDOCS7) ## Create manpages
+build_html_docs: $(HTMLDOCS1) $(HTMLDOCS3) $(HTMLDOCS5) $(HTMLDOCS7) ## Create HTML documentation
 
 build_generated: $(GENERATED_MANDATORY)
 build_libs_nodep: libcrypto.pc libssl.pc openssl.pc
@@ -531,10 +537,14 @@ build_all_generated: $(GENERATED_MANDATORY) $(GENERATED) build_docs
 	@echo "         then make will fail..."
 	@ : {- output_on() if $disabled{makedepend}; "" -}
 
-all: build_sw build_docs
+##@ Help
+.PHONY: help
+help: ## Show this help screen
+	@$(PERL) $(SRCDIR)/util/help.pl $(BLDDIR)/Makefile
 
-test: tests
-{- dependmagic('tests'); -}: build_programs_nodep build_modules_nodep link-utils run_tests
+##@ Testing
+test: tests ## Run tests (alias of "tests")
+{- dependmagic('tests', 'Run tests'); -}: build_programs_nodep build_modules_nodep link-utils run_tests
 run_tests:
 	@ : {- output_off() if $disabled{tests}; "" -}
 	( SRCTOP=$(SRCDIR) \
@@ -547,16 +557,14 @@ run_tests:
 	@echo "Tests are not supported with your chosen Configure options"
 	@ : {- output_on() if !$disabled{tests}; "" -}
 
-list-tests:
+list-tests: ## List available tests that can be invoked via "make test TESTS=<name>"
 	@ : {- output_off() if $disabled{tests}; "" -}
 	$(MAKE) run_tests TESTS=list
 	@ : {- if ($disabled{tests}) { output_on(); } else { output_off(); } "" -}
 	@echo "Tests are not supported with your chosen Configure options"
 	@ : {- output_on() if !$disabled{tests}; "" -}
 
-install: install_sw install_ssldirs install_docs {- $disabled{fips} ? "" : "install_fips" -}
-
-uninstall: uninstall_docs uninstall_sw {- $disabled{fips} ? "" : "uninstall_fips" -}
+##@ Workspace cleaning
 
 libclean:
 	@set -e; for s in $(SHLIB_INFO); do \
@@ -581,7 +589,7 @@ libclean:
 	$(RM) $(LIBS)
 	$(RM) *{- platform->defext() -}
 
-clean: libclean
+clean: libclean ## Clean the workspace, keep the configuration
 	$(RM) $(HTMLDOCS1)
 	$(RM) $(HTMLDOCS3)
 	$(RM) $(HTMLDOCS5)
@@ -601,7 +609,7 @@ clean: libclean
 	$(RM) openssl.pc libcrypto.pc libssl.pc
 	-find . -type l \! -name '.*' -exec $(RM) {} \;
 
-distclean: clean
+distclean: clean ## Clean and remove the configuration
 	$(RM) include/openssl/configuration.h
 	$(RM) configdata.pm
 	$(RM) Makefile
@@ -614,14 +622,19 @@ depend: Makefile
 	@: {- output_on() if $disabled{makedepend}; "" -}
 
 # Install helper targets #############################################
+##@ Installation
+
+install: install_sw install_ssldirs install_docs {- $disabled{fips} ? "" : "install_fips" -} ## Install software and documentation, create OpenSSL directories
+
+uninstall: uninstall_docs uninstall_sw {- $disabled{fips} ? "" : "uninstall_fips" -} ## Uninstall software and documentation
 
-install_sw: install_dev install_engines install_modules install_runtime
+install_sw: install_dev install_engines install_modules install_runtime ## Install just the software and libraries
 
-uninstall_sw: uninstall_runtime uninstall_modules uninstall_engines uninstall_dev
+uninstall_sw: uninstall_runtime uninstall_modules uninstall_engines uninstall_dev ## Uninstall the software and libraries
 
-install_docs: install_man_docs install_html_docs
+install_docs: install_man_docs install_html_docs ## Install manpages and HTML documentation
 
-uninstall_docs: uninstall_man_docs uninstall_html_docs
+uninstall_docs: uninstall_man_docs uninstall_html_docs ## Uninstall manpages and HTML documentation
 	$(RM) -r $(DESTDIR)$(DOCDIR)
 
 {- output_off() if $disabled{fips}; "" -}
@@ -1108,10 +1121,11 @@ uninstall_image_docs:
 	done
 
 # Developer targets (note: these are only available on Unix) #########
+##@ Code maintenence
 
 # It's important that generate_buildinfo comes after ordinals, as ordinals
 # is sensitive to build.info changes.
-update: generate errors ordinals generate_buildinfo
+update: generate errors ordinals generate_buildinfo ## Update errors, ordinals and build info
 
 .PHONY: generate generate_apps generate_crypto_bn generate_crypto_objects \
           generate_crypto_conf generate_crypto_asn1 generate_fuzz_oids
@@ -1122,7 +1136,7 @@ generate: generate_apps generate_crypto_bn generate_crypto_objects \
 generate_buildinfo: generate_doc_buildinfo
 
 .PHONY: doc-nits md-nits
-doc-nits: build_generated_pods
+doc-nits: build_generated_pods ## Evaluate OpenSSL documentation
 	$(PERL) $(SRCDIR)/util/find-doc-nits -c -n -l -e
 
 # This uses "mdl", the markdownlint application, which is written in ruby.
@@ -1131,21 +1145,21 @@ doc-nits: build_generated_pods
 # Another option is at https://snapcraft.io/install/mdl/debian
 # Finally, there's a Node.js version, which we haven't tried, that
 # can be found at https://github.com/DavidAnson/markdownlint
-md-nits:
+md-nits: ## Evaluate markdown files via "mdl"
 	mdl -s util/markdownlint.rb .
 
 # Test coverage is a good idea for the future
 #coverage: $(PROGRAMS) $(TESTPROGRAMS)
 #	...
 
 .PHONY: lint
-lint:
+lint: ## Evaluate C code via "splint"
 	@( cd $(SRCDIR); \
            echo splint -DLINT -posixlib -preproc -D__gnuc_va_list=void \
 	   -I. -Iinclude -Iapps/include $(CRYPTOHEADERS) $(SSLHEADERS) $(SRCS) )
 
 .PHONY: check-format
-check-format:
+check-format: ## Evaluate C code according to OpenSSL coding standards
 	( cd $(SRCDIR); $(PERL) util/check-format.pl \
 			$(SRCS) \$(CRYPTOHEADERS) $(SSLHEADERS) )
 

util/help.pl

@@ -0,0 +1,25 @@
+#! /usr/bin/env perl
+# Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.
+#
+# Licensed under the Apache License 2.0 (the "License").  You may not use
+# this file except in compliance with the License.  You can obtain a copy
+# in the file LICENSE in the source distribution or at
+# https://www.openssl.org/source/license.html
+
+die "No input files" if scalar @ARGV == 0;
+$FS = ':.*##';
+printf "\nUsage:\n  make <OPTIONS> \033[36m<target>\033[0m\n";
+
+while (<>) {
+    chomp;	# strip record separator
+    @Fld = split($FS, $_, -1);
+    if (/^[a-zA-Z0-9_\-]+:.*?##/) {
+	printf "  \033[36m%-15s\033[0m %s\n", $Fld[0], $Fld[1]
+    }
+    if (/^##@/) {
+	printf "\n\033[1m%s\033[0m\n", substr($Fld[$_], (5)-1);
+    }
+}
+
+printf "\nNote: This list is not all-inclusive\n";
+