by Lance Pollard
Emergent is a project generation toolkit, not just for ruby and software development, but
for everyday projects. It allows you to convert any project to a template, to create template projects from scratch, and to massively replace complex patterns in select files/filetypes/directories.
This is how you create a new project, add a file, convert it to a generator, save it into your “project template cache”, and use it as a template to create a new project.
- emergent create generator my_template
- # edit the configuration variables for your name, website, etc.
- # press enter in the terminal
- # add a sample file somewhere other than the my_template/emergent directory
- emergent convert generator my_template
- emergent save generator my_template
- emergent create my_template new_project
- # repeat :)
Each Emergent project begins with these files, all located in emergent/my_project:
- config/configuration.yml:: # Assign your basic variables here
- config/generator_replacements.yml:: # Words to replace for when you convert your project to a generator
- config/project_replacements.yml:: # Words to replace when you convert your generator to a project
- config/list.yml:: # Makes it easy to list files, search results, etc.
- copyright.txt:: # Sample Copyright notice
- generators/my_generator/my_generator.rb:: # Generator Template, does the work
- generators/my_generator/commands.rb:: # The accepted commands for your project, and how they are handled
- tasks/*:: # Rake tasks for gemifying, testing, etc.
The Configuration file is where you define what all your variables mean. Some projects may have special variables defined, like author_name or project_path, and you can customize these here.
The Replacement files are there to make it easy for you to define patterns for replacing text to and from your generators. This is very sophisticated and will help you tons.
The List file is there to help you search through directories, over the internet for patterns, etc., and to list the results, in any format you’d like, wherever you’d like.
The Generator file specifies the templates you’re going to use in your new projects. You are free to go in there and define options and all that if you’d like.
emergent create generator my_generator
Creates a new project, “my_generator”, from the template project, “generator”. You can also specify options.
emergent config generator my_random_project
Configures your “my_random_project” into an Emergent project, by creating the same files the “create” command does. It bases its files off the “generator” in the above command.
emergent convert generator my_generator
Converts your “my_generator” project into its own generator, as governed by the “generator” directives. Stores this in the “my_generator/emergent/generators/my_generator_generator” directory, to be later saved if so desired.
You can now choose to govern your “my_generator” project from either the “generator” directives, or the newly created “my_generator” directives.
emergent edit my_generator .
emergent edit generator my_generator
emergent edit generator my_generator -R . -I as,xml,mxml,rb -P “MXML” -S “Mxml” —rename-files
Allows you to edit your project (the “convert” command edits your generator), where you may find/replace text into other text. The “list” command has the “collect/place” functionality.
emergent save generator my_generator
Saves your “converted” “my_generator” into your local cache, so you can globally use it later as a template project.
emergent list generator -R . -W ./my_file.txt -P “Im a PATTERN” -C “Im”,"a “,”PATTERN" -S “1” -A “Write after me” -O 2
Emergent provides the following rake tasks:
ann # Alias to ann:announcement
ann:announcement # Create an announcement file
ann:email # Send an email announcement
autotest # Run the autotest loop
emergent:debug # Show the PROJ open struct
clean # Remove any temporary products.
clobber # Remove any generated file.
doc # Alias to doc:rdoc
doc:rdoc # Build the rdoc HTML Files
doc:release # Publish RDoc to RubyForge
doc:rerdoc # Force a rebuild of the RDOC files
doc:ri # Generate ri locally for testing
gem # Alias to gem:package
gem:cleanup # Cleanup the gem
gem:debug # Show information about the gem
gem:install # Install the gem
gem:package # Build all the packages
gem:reinstall # Reinstall the gem
gem:release # Package and upload to RubyForge
gem:repackage # Force a rebuild of the package files
gem:spec # Write the gemspec
gem:uninstall # Uninstall the gem
git:create_tag # Create a new tag in the Git repository
git:show_tags # Show tags from the Git repository
notes # Enumerate all annotations
notes:fixme # Enumerate all FIXME annotations
notes:optimize # Enumerate all OPTIMIZE annotations
notes:todo # Enumerate all TODO annotations
spec # Alias to spec:run
spec:rcov # Run all specs with RCov
spec:run # Run all specs with basic output
spec:specdoc # Run all specs with text output
spec:verify # Verify that rcov coverage is at least 90.0%
svn:create_tag # Create a new tag in the SVN repository
svn:show_tags # Show tags from the SVN repository
test # Alias to test:run
test:rcov # Run rcov on the unit tests
test:run # Run tests for run
The rake tasks in the Emergent framework can be found in the “tasks”
directory. Add your own tasks there when you need more functionality.
These are inspired from the Hoe and Mr. Bones projects.